markifact-com Connections API

openapi: 3.2.0
info:
  title: Markifact Connections API
  version: 1.0.0
  description: API for managing Markifact workspace connections.
servers:
- url: https://api.markifact.com
security:
- bearerAuth: []
tags:
- name: Connections
paths:
  /v1/connections:
    get:
      operationId: listConnections
      summary: List connections
      description: List API-visible connections in your Markifact team workspace.
      tags:
      - Connections
      parameters:
      - name: external_id
        in: query
        required: false
        schema:
          type: string
        description: Filter connections by the external ID you provided when creating the auth link.
      - name: type
        in: query
        required: false
        schema:
          type: string
          example: ga4
        description: Filter connections by connection type.
      responses:
        '200':
          description: Connections returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Connection'
        '401':
          description: Invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createConnection
      summary: Create connection
      description: Create a connection from credentials you already hold, for any connection type whose auth_methods include "manual". The credentials are verified with the provider before anything is stored, so a successful response means the connection works. OAuth-only types cannot be created this way; use POST /v1/connections/auth-link instead.
      tags:
      - Connections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConnectionRequest'
      responses:
        '200':
          description: Connection created and verified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        '400':
          description: The type cannot be created from credentials, a credential field is missing or unrecognised, or the provider rejected the credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: White-label connections require the Team plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/connections/types:
    get:
      operationId: listConnectionTypes
      summary: List connection types
      description: List every connection type Markifact supports, with how each one can be authenticated and, for manual types, the credential fields it expects.
      tags:
      - Connections
      responses:
        '200':
          description: Connection types returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConnectionType'
  /v1/connections/{connection_id}:
    get:
      operationId: getConnection
      summary: Get connection
      description: Find connections by Markifact connection ID or your external ID.
      tags:
      - Connections
      parameters:
      - name: connection_id
        in: path
        required: true
        schema:
          type: string
        description: Markifact connection ID by default, or your external ID when lookup_by is external_id.
      - name: lookup_by
        in: query
        required: false
        schema:
          type: string
          enum:
          - id
          - external_id
          default: id
        description: Use id for Markifact connection ID lookup, or external_id for your external ID.
      responses:
        '200':
          description: Matching connections returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Connection'
        '404':
          description: Connection not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteConnection
      summary: Delete connection
      description: Delete an API-visible connection from your Markifact team workspace.
      tags:
      - Connections
      parameters:
      - name: connection_id
        in: path
        required: true
        schema:
          type: string
        description: Public Markifact connection ID.
      responses:
        '200':
          description: Deleted connection returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        '404':
          description: Connection not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/connections/auth-link:
    post:
      operationId: createAuthLink
      summary: Create auth link
      description: Create a shareable OAuth link that connects an external account to your Markifact team.
      tags:
      - Connections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAuthLinkRequest'
      responses:
        '200':
          description: Auth link created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthLink'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/connections/auth-links/{auth_link_id}/status:
    get:
      operationId: getAuthLinkStatus
      summary: Get auth link status
      description: Check whether an auth link is pending, expired, or connected.
      tags:
      - Connections
      parameters:
      - name: auth_link_id
        in: path
        required: true
        schema:
          type: string
        description: Auth link ID returned by Create auth link.
      responses:
        '200':
          description: Auth link status returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthLinkStatus'
        '404':
          description: Auth link not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AuthLink:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
        expires_at:
          type: integer
          format: int64
      required:
      - id
      - url
      - expires_at
    CreateAuthLinkRequest:
      type: object
      properties:
        connection_type:
          type: string
          example: ga4
        redirect_url:
          type: string
          format: uri
          example: https://example.com/oauth/callback
        external_id:
          type: string
          maxLength: 255
          example: customer_123
        is_private:
          type: boolean
          default: false
          description: Whether the created connection should be private to the API-key user. Defaults to false, meaning shared with the workspace so other team members can see and use it.
      required:
      - connection_type
    CreateConnectionRequest:
      type: object
      properties:
        connection_type:
          type: string
          example: gads
          description: A connection type whose auth_methods include "manual". See GET /v1/connections/types.
        name:
          type: string
          maxLength: 100
          example: Acme Agency Google Ads
          description: Your label for the connection. For white-label types, posting the same type and name again replaces the stored credentials in place. Slack and Shopify are keyed on the workspace and store instead, and API-key types (Ahrefs, SEMrush, Adjust, DataForSEO, OpenAI Ads) always create a new connection.
        credentials:
          type: object
          additionalProperties:
            type: string
          description: Exactly the credential_fields the type lists. A missing or unrecognised field is rejected before any call to the provider.
          example:
            client_id: 1234567890-abc123.apps.googleusercontent.com
            client_secret: GOCSPX-...
            refresh_token: 1//0g...
        is_private:
          type: boolean
          default: false
          description: Whether the connection should be private to the API-key user. Defaults to false, meaning shared with the workspace so other team members can see and use it. Omit it when replacing credentials on an existing connection and the current visibility is kept.
      required:
      - connection_type
      - name
      - credentials
    Connection:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Public Markifact connection ID.
        type:
          type: string
          description: Connection type.
        display_name:
          type:
          - string
          - 'null'
        external_id:
          type:
          - string
          - 'null'
        is_private:
          type: boolean
        created_at:
          type:
          - integer
          - 'null'
          format: int64
        updated_at:
          type:
          - integer
          - 'null'
          format: int64
      required:
      - id
      - type
      - is_private
    ConnectionType:
      type: object
      properties:
        type:
          type: string
        name:
          type: string
        auth_methods:
          type: array
          items:
            type: string
            enum:
            - oauth
            - manual
          description: How this type can be authenticated. An "oauth" type accepts a shared auth link; a "manual" type is created by posting credentials to POST /v1/connections. A type listing both can be connected either way, and using your own app there is a white-label connection.
        credential_fields:
          type:
          - array
          - 'null'
          items:
            type: string
          description: 'Credential field names a manual connection of this type expects. Null for types that take no credentials: OAuth-only types, and the ones connected only in the Markifact app.'
        docs_url:
          type:
          - string
          - 'null'
          format: uri
          description: Plain-markdown page explaining where each credential comes from, suitable for an agent to read directly. Null for types that have no page yet.
          example: https://docs.markifact.com/nodes/meta_ads/meta_ads_custom_app.md
      required:
      - type
      - name
      - auth_methods
    Error:
      type: object
      properties:
        detail: {}
    AuthLinkStatus:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
          - pending
          - connected
          - expired
        connection_type:
          type: string
        connection_id:
          type:
          - string
          - 'null'
        external_id:
          type:
          - string
          - 'null'
        expires_at:
          type: integer
          format: int64
        consumed_at:
          type:
          - integer
          - 'null'
          format: int64
        created_at:
          type: integer
          format: int64
        updated_at:
          type: integer
          format: int64
        connections:
          type: array
          items:
            $ref: '#/components/schemas/Connection'
      required:
      - id
      - status
      - connection_type
      - expires_at
      - created_at
      - updated_at
      - connections
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer