Influence Tools API

openapi: 3.2.0
info:
  description: The existing tool-oriented HTTP API. Discover tools available to your credential before calling them. Tool inputs & outputs depend on the selected tool; read its discovered schema & supported workflow. Requests accept no query parameters. Documentation does not grant access or bypass product approval requirements.
  title: Influence HTTP Tools API
  version: '1'
servers:
- url: https://influence.so
security:
- bearerAuth: []
tags:
- name: Tools
  x-displayName: Tools
paths:
  /api/v1/tools:
    get:
      description: Return tool names, descriptions, scopes, confirmation requirements & input schemas visible to the bearer credential.
      operationId: listTools
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolCatalog'
          description: Available tool descriptors.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: Invalid request. Query parameters are not accepted. Tool validation failures may use a tool error envelope.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: Missing, invalid or expired bearer credential.
          headers:
            WWW-Authenticate:
              schema:
                const: Bearer realm="Influence"
                type: string
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: The credential lacks required permissions.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: The machine API or requested tool is unavailable.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: Rate limit exceeded. The error is retryable.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: The API or its upstream execution is unavailable.
      summary: Discover Available Tools
      tags:
      - Tools
  /api/v1/tools/{tool}/call:
    post:
      description: 'Call a tool whose discovery descriptor has confirmation: "none". This includes reading data & continuing an already authorized upload. Send {input: {...}} using the schema matching the path’s tool name. JSON requests are limited to 65,536 bytes. A 200 response can contain ok:false.'
      operationId: callTool
      parameters:
      - description: Tool name returned by GET /api/v1/tools. Discovery is filtered by this credential’s permissions; schema presence does not establish availability.
        in: path
        name: tool
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResult'
          description: Tool result; inspect ok & error.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/TransportError'
                - $ref: '#/components/schemas/ToolError'
          description: Invalid request. Query parameters are not accepted. Tool validation failures may use a tool error envelope.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: Missing, invalid or expired bearer credential.
          headers:
            WWW-Authenticate:
              schema:
                const: Bearer realm="Influence"
                type: string
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: The credential lacks required permissions.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: The machine API or requested tool is unavailable.
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolError'
          description: The request exceeds the byte limit.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: Rate limit exceeded. The error is retryable.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: The API or its upstream execution is unavailable.
      summary: Call a Tool Without Confirmation
      tags:
      - Tools
  /api/v1/tools/{tool}/confirm:
    post:
      description: Confirm the same prepared input with both required headers. Additional publishing review & human approval rules still apply. A 200 response can contain ok:false; accepted or scheduled work is not proof of publication. JSON requests are limited to 65,536 bytes.
      operationId: confirmTool
      parameters:
      - description: Tool name returned by GET /api/v1/tools. Discovery is filtered by this credential’s permissions; schema presence does not establish availability.
        in: path
        name: tool
        required: true
        schema:
          type: string
      - description: The exact confirmationCapability returned by prepare. Send it only in this header, with the same input, before expiresAt.
        in: header
        name: X-Publish-Confirmation
        required: true
        schema:
          $ref: '#/components/schemas/ConfirmationCapability'
      - description: Caller-generated retry identity. Preserve this key, capability & input after an uncertain response.
        in: header
        name: Idempotency-Key
        required: true
        schema:
          $ref: '#/components/schemas/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResult'
          description: Tool result; inspect ok & error.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/TransportError'
                - $ref: '#/components/schemas/ToolError'
          description: Invalid request. Query parameters are not accepted. Tool validation failures may use a tool error envelope.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: Missing, invalid or expired bearer credential.
          headers:
            WWW-Authenticate:
              schema:
                const: Bearer realm="Influence"
                type: string
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: The credential lacks required permissions.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: The machine API or requested tool is unavailable.
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolError'
          description: The request exceeds the byte limit.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: Rate limit exceeded. The error is retryable.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: The API or its upstream execution is unavailable.
      summary: Confirm a Mutation
      tags:
      - Tools
  /api/v1/tools/{tool}/prepare:
    post:
      description: 'Prepare a mutation with {input: {...}}. Preparation does not approve or execute publication. A successful preparation returns confirmationCapability & expiresAt; a tool failure can still use HTTP 200. JSON requests are limited to 65,536 bytes.'
      operationId: prepareTool
      parameters:
      - description: Tool name returned by GET /api/v1/tools. Discovery is filtered by this credential’s permissions; schema presence does not establish availability.
        in: path
        name: tool
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/PreparedTool'
                - $ref: '#/components/schemas/ToolError'
          description: Preparation or tool failure.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/TransportError'
                - $ref: '#/components/schemas/ToolError'
          description: Invalid request. Query parameters are not accepted. Tool validation failures may use a tool error envelope.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: Missing, invalid or expired bearer credential.
          headers:
            WWW-Authenticate:
              schema:
                const: Bearer realm="Influence"
                type: string
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: The credential lacks required permissions.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: The machine API or requested tool is unavailable.
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolError'
          description: The request exceeds the byte limit.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: Rate limit exceeded. The error is retryable.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransportError'
          description: The API or its upstream execution is unavailable.
      summary: Prepare a Mutation
      tags:
      - Tools
components:
  schemas:
    ToolMetadataValue:
      anyOf:
      - type: string
      - type: number
      - type: boolean
      - type: 'null'
      - type: array
        items:
          $ref: '#/components/schemas/ToolMetadataValue'
      - type: object
        propertyNames:
          type: string
        additionalProperties:
          $ref: '#/components/schemas/ToolMetadataValue'
    ToolRequest:
      type: object
      properties:
        input:
          type: object
          propertyNames:
            type: string
            minLength: 1
            maxLength: 128
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
      required:
      - input
      additionalProperties: false
    PreparedTool:
      type: object
      properties:
        confirmationCapability:
          description: Return this value in the X-Publish-Confirmation header before expiresAt.
          $ref: '#/components/schemas/ConfirmationCapability'
        expiresAt:
          type: string
          format: date-time
          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
        inputDigest:
          type: string
          pattern: ^[0-9a-f]{64}$
        status:
          type: string
          const: confirmation_required
        summary:
          $ref: '#/components/schemas/JsonValue'
        toolName:
          type: string
          enum:
          - adAuditQuote
          - adAuditStart
          - adAuditGet
          - adAuditList
          - search
          - fetch
          - profileGet
          - connectionStatusGet
          - accountList
          - campaignGet
          - campaignList
          - campaignDraftSave
          - mediaList
          - mediaImport
          - mediaUploadCreate
          - mediaUploadPart
          - mediaUploadComplete
          - mediaUploadGet
          - mediaUploadAbort
          - mediaGet
          - campaignReview
          - campaignReviewGet
          - campaignReviewExecute
          - campaignScheduleBatchReview
          - campaignScheduleBatchExecute
          - scheduleList
          - brandContextGet
          - insightsAccountList
          - insightsPostList
          - insightsRefresh
          - campaignPlanGet
          - campaignPlanGenerate
          - imageGenerationQuote
          - imageGenerationStart
          - imageGenerationList
          - integrationList
          - groupList
          - integrationSchema
          - devtoOrganizationList
          - devtoTagList
          - discordChannelList
          - discourseCategoryList
          - discourseTagList
          - discourseTopicSearch
          - dribbbleTeamList
          - ghostAuthorList
          - ghostNewsletterList
          - ghostTagList
          - ghostTierList
          - hashnodePublicationList
          - lemmyCommunitySearch
          - listmonkListsGet
          - listmonkTemplateList
          - mattermostChannelList
          - meweGroupList
          - pinterestBoardList
          - redditSubredditRequirementsGet
          - redditSubredditSearch
          - slackChannelList
          - teamsChannelList
          - tiktokCreatorInfoGet
          - vkDestinationList
          - whopCompanyList
          - whopExperienceList
          - wordpressCategoryList
          - wordpressPostTypeList
          - wordpressTagList
          - wrapcastChannelSearch
          - integrationSchedulePostTool
          - postsListTool
          - postSettingsTool
      required:
      - confirmationCapability
      - expiresAt
      - inputDigest
      - status
      - toolName
      additionalProperties: false
    ConfirmationCapability:
      type: string
      minLength: 32
      maxLength: 4096
      pattern: ^[A-Za-z0-9._~-]+$
    SchemaValue:
      anyOf:
      - type: string
      - type: number
      - type: boolean
      - type: 'null'
      - type: array
        items:
          $ref: '#/components/schemas/SchemaValue'
      - type: object
        propertyNames:
          type: string
        additionalProperties:
          $ref: '#/components/schemas/SchemaValue'
    ToolError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - AI_SCHEDULING_LIMIT_REACHED
              - AI_SCHEDULING_UNAVAILABLE
              - INVALID_INPUT
              - FORBIDDEN
              - NOT_FOUND
              - CONFLICT
              - FEATURE_DISABLED
              - CONFIRMATION_REQUIRED
              - CONFIRMATION_INVALID
              - UPSTREAM_FAILED
              - NEEDS_REVIEW
              - INTERNAL
            message:
              type: string
              minLength: 1
              maxLength: 2048
            retryable:
              type: boolean
          required:
          - code
          - message
          - retryable
          additionalProperties: false
        ok:
          type: boolean
          const: false
        toolName:
          type: string
          enum:
          - adAuditQuote
          - adAuditStart
          - adAuditGet
          - adAuditList
          - search
          - fetch
          - profileGet
          - connectionStatusGet
          - accountList
          - campaignGet
          - campaignList
          - campaignDraftSave
          - mediaList
          - mediaImport
          - mediaUploadCreate
          - mediaUploadPart
          - mediaUploadComplete
          - mediaUploadGet
          - mediaUploadAbort
          - mediaGet
          - campaignReview
          - campaignReviewGet
          - campaignReviewExecute
          - campaignScheduleBatchReview
          - campaignScheduleBatchExecute
          - scheduleList
          - brandContextGet
          - insightsAccountList
          - insightsPostList
          - insightsRefresh
          - campaignPlanGet
          - campaignPlanGenerate
          - imageGenerationQuote
          - imageGenerationStart
          - imageGenerationList
          - integrationList
          - groupList
          - integrationSchema
          - devtoOrganizationList
          - devtoTagList
          - discordChannelList
          - discourseCategoryList
          - discourseTagList
          - discourseTopicSearch
          - dribbbleTeamList
          - ghostAuthorList
          - ghostNewsletterList
          - ghostTagList
          - ghostTierList
          - hashnodePublicationList
          - lemmyCommunitySearch
          - listmonkListsGet
          - listmonkTemplateList
          - mattermostChannelList
          - meweGroupList
          - pinterestBoardList
          - redditSubredditRequirementsGet
          - redditSubredditSearch
          - slackChannelList
          - teamsChannelList
          - tiktokCreatorInfoGet
          - vkDestinationList
          - whopCompanyList
          - whopExperienceList
          - wordpressCategoryList
          - wordpressPostTypeList
          - wordpressTagList
          - wrapcastChannelSearch
          - integrationSchedulePostTool
          - postsListTool
          - postSettingsTool
      required:
      - error
      - ok
      - toolName
      additionalProperties: false
    IdempotencyKey:
      type: string
      minLength: 16
      maxLength: 200
      pattern: ^[A-Za-z0-9._:-]+$
    ToolResult:
      oneOf:
      - type: object
        properties:
          ok:
            type: boolean
            const: true
          output:
            $ref: '#/components/schemas/JsonValue'
          toolName:
            type: string
            enum:
            - adAuditQuote
            - adAuditStart
            - adAuditGet
            - adAuditList
            - search
            - fetch
            - profileGet
            - connectionStatusGet
            - accountList
            - campaignGet
            - campaignList
            - campaignDraftSave
            - mediaList
            - mediaImport
            - mediaUploadCreate
            - mediaUploadPart
            - mediaUploadComplete
            - mediaUploadGet
            - mediaUploadAbort
            - mediaGet
            - campaignReview
            - campaignReviewGet
            - campaignReviewExecute
            - campaignScheduleBatchReview
            - campaignScheduleBatchExecute
            - scheduleList
            - brandContextGet
            - insightsAccountList
            - insightsPostList
            - insightsRefresh
            - campaignPlanGet
            - campaignPlanGenerate
            - imageGenerationQuote
            - imageGenerationStart
            - imageGenerationList
            - integrationList
            - groupList
            - integrationSchema
            - devtoOrganizationList
            - devtoTagList
            - discordChannelList
            - discourseCategoryList
            - discourseTagList
            - discourseTopicSearch
            - dribbbleTeamList
            - ghostAuthorList
            - ghostNewsletterList
            - ghostTagList
            - ghostTierList
            - hashnodePublicationList
            - lemmyCommunitySearch
            - listmonkListsGet
            - listmonkTemplateList
            - mattermostChannelList
            - meweGroupList
            - pinterestBoardList
            - redditSubredditRequirementsGet
            - redditSubredditSearch
            - slackChannelList
            - teamsChannelList
            - tiktokCreatorInfoGet
            - vkDestinationList
            - whopCompanyList
            - whopExperienceList
            - wordpressCategoryList
            - wordpressPostTypeList
            - wordpressTagList
            - wrapcastChannelSearch
            - integrationSchedulePostTool
            - postsListTool
            - postSettingsTool
        required:
        - ok
        - output
        - toolName
        additionalProperties: false
      - $ref: '#/components/schemas/ToolError'
    CatalogMetadataValue:
      anyOf:
      - type: string
      - type: number
      - type: boolean
      - type: 'null'
      - type: array
        items:
          $ref: '#/components/schemas/CatalogMetadataValue'
      - type: object
        propertyNames:
          type: string
        additionalProperties:
          $ref: '#/components/schemas/CatalogMetadataValue'
    JsonValue:
      anyOf:
      - type: string
        maxLength: 8192
      - type: number
      - type: boolean
      - type: 'null'
      - maxItems: 2000
        type: array
        items:
          $ref: '#/components/schemas/JsonValue'
      - type: object
        propertyNames:
          type: string
          minLength: 1
          maxLength: 128
        additionalProperties:
          $ref: '#/components/schemas/JsonValue'
    ToolCatalog:
      type: object
      properties:
        tools:
          type: array
          items:
            type: object
            properties:
              annotations:
                type: object
                properties:
                  destructiveHint:
                    type: boolean
                  idempotentHint:
                    type: boolean
                  openWorldHint:
                    type: boolean
                  readOnlyHint:
                    type: boolean
                required:
                - destructiveHint
                - idempotentHint
                - openWorldHint
                - readOnlyHint
                additionalProperties: false
              confirmation:
                type: string
                enum:
                - none
                - required
              description:
                type: string
                minLength: 1
                maxLength: 1024
              gate:
                type: string
                enum:
                - core
                - generative-ai
              mutability:
                type: string
                enum:
                - read
                - external-read
                - write
                - external-write
              name:
                type: string
                enum:
                - adAuditQuote
                - adAuditStart
                - adAuditGet
                - adAuditList
                - search
                - fetch
                - profileGet
                - connectionStatusGet
                - accountList
                - campaignGet
                - campaignList
                - campaignDraftSave
                - mediaList
                - mediaImport
                - mediaUploadCreate
                - mediaUploadPart
                - mediaUploadComplete
                - mediaUploadGet
                - mediaUploadAbort
                - mediaGet
                - campaignReview
                - campaignReviewGet
                - campaignReviewExecute
                - campaignScheduleBatchReview
                - campaignScheduleBatchExecute
                - scheduleList
                - brandContextGet
                - insightsAccountList
                - insightsPostList
                - insightsRefresh
                - campaignPlanGet
                - campaignPlanGenerate
                - imageGenerationQuote
                - imageGenerationStart
                - imageGenerationList
                - integrationList
                - groupList
                - integrationSchema
                - devtoOrganizationList
                - devtoTagList
                - discordChannelList
                - discourseCategoryList
                - discourseTagList
                - discourseTopicSearch
                - dribbbleTeamList
                - ghostAuthorList
                - ghostNewsletterList
                - ghostTagList
                - ghostTierList
                - hashnodePublicationList
                - lemmyCommunitySearch
                - listmonkListsGet
                - listmonkTemplateList
                - mattermostChannelList
                - meweGroupList
                - pinterestBoardList
                - redditSubredditRequirementsGet
                - redditSubredditSearch
                - slackChannelList
                - teamsChannelList
                - tiktokCreatorInfoGet
                - vkDestinationList
                - whopCompanyList
                - whopExperienceList
                - wordpressCategoryList
                - wordpressPostTypeList
                - wordpressTagList
                - wrapcastChannelSearch
                - integrationSchedulePostTool
                - postsListTool
                - postSettingsTool
              scopes:
                maxItems: 4
                type: array
                items:
                  type: string
                  enum:
                  - integrations:read
                  - posts:read
                  - posts:write
                  - media:read
                  - media:write
                  - generation:read
                  - generation:write
              title:
                type: string
                minLength: 1
                maxLength: 80
              inputSchema:
                type: object
                properties:
                  type:
                    type: string
                    const: object
                required:
                - type
                additionalProperties:
                  $ref: '#/components/schemas/SchemaValue'
            required:
            - annotations
            - confirmation
            - description
            - gate
            - mutability
            - name
            - scopes
            - title
            - inputSchema
            additionalProperties:
              $ref: '#/components/schemas/ToolMetadataValue'
      required:
      - tools
      additionalProperties:
        $ref: '#/components/schemas/CatalogMetadataValue'
    TransportError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
          required:
          - code
          - message
          - retryable
          additionalProperties: false
      required:
      - error
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      description: Influence scoped API key or supported OAuth access token. Keep credentials out of URLs & tool input.
      scheme: bearer
      type: http