IntegrationOS Link API

openapi: 3.2.0
info:
  description: The One API. Universal API integration platform for AI agents and applications.
  license:
    name: ''
  title: One Link API
  version: 5.35.0
tags:
- description: 'The live customer link: status, API-key rotation, and the customer-facing connect flow'
  name: Link
paths:
  /v1/link/connections:
    get:
      operationId: list_link_connections
      parameters:
      - description: 'Items per page. Default 20, hard-capped at 150. `limit=0` is

          treated as 1. Larger values silently clamp.'
        example: 20
        in: query
        name: limit
        required: false
        schema:
          default: 20
          format: int64
          maximum: 150
          minimum: 0
          type: integer
      - description: Page number for pagination (1-indexed). Defaults to 1.
        example: 1
        in: query
        name: page
        required: false
        schema:
          default: 1
          format: int64
          minimum: 0
          type: integer
      - description: 'Number of items to skip before the first returned item. Defaults to 0.

          Most callers should leave this at 0 and rely on `page` + `limit`.'
        example: 0
        in: query
        name: skip
        required: false
        schema:
          default: 0
          format: int64
          minimum: 0
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paginated_ConnectionView'
          description: Connections owned by the invitation's project
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource already exists
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Rate limit exceeded
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      tags:
      - Link
      summary: List link connections
      x-summary-source: derived
  /v1/link/init:
    post:
      operationId: init_link_connection
      parameters:
      - description: 'Items per page. Default 20, hard-capped at 150. `limit=0` is

          treated as 1. Larger values silently clamp.'
        example: 20
        in: query
        name: limit
        required: false
        schema:
          default: 20
          format: int64
          maximum: 150
          minimum: 0
          type: integer
      - description: Page number for pagination (1-indexed). Defaults to 1.
        example: 1
        in: query
        name: page
        required: false
        schema:
          default: 1
          format: int64
          minimum: 0
          type: integer
      - description: 'Number of items to skip before the first returned item. Defaults to 0.

          Most callers should leave this at 0 and rely on `page` + `limit`.'
        example: 0
        in: query
        name: skip
        required: false
        schema:
          default: 0
          format: int64
          minimum: 0
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrepareInitParams'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitResponse'
          description: Connection initialized
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource already exists
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Rate limit exceeded
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      tags:
      - Link
      summary: Init link connection
      x-summary-source: derived
  /v1/link/organizations/{org_id}/{id}:
    get:
      operationId: retrieve_link
      parameters:
      - description: Organization ID
        in: path
        name: org_id
        required: true
        schema:
          format: uuid
          type: string
      - description: Link ID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveResponse'
          description: Link details + activated connectors
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource already exists
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Rate limit exceeded
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - Session: []
      tags:
      - Link
      summary: Retrieve link
      x-summary-source: derived
  /v1/link/organizations/{org_id}/{id}/rotate:
    post:
      operationId: rotate_link
      parameters:
      - description: Organization ID
        in: path
        name: org_id
        required: true
        schema:
          format: uuid
          type: string
      - description: Link ID
        in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RotateResponse'
          description: Link API key rotated
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource already exists
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Rate limit exceeded
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - Session: []
      tags:
      - Link
      summary: Rotate link
      x-summary-source: derived
  /v1/link/resolve:
    get:
      operationId: resolve_link
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolveResponse'
          description: Resolved invitation + connector entries
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource already exists
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Rate limit exceeded
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      tags:
      - Link
      summary: Resolve link
      x-summary-source: derived
components:
  schemas:
    BrandingSnapshot:
      properties:
        customerFacingName:
          type: string
        darkLogoUrl:
          type:
          - string
          - 'null'
        lightLogoUrl:
          type:
          - string
          - 'null'
        successMessage:
          type: string
        welcomeMessage:
          type: string
      required:
      - customerFacingName
      - welcomeMessage
      - successMessage
      type: object
    ConnectionStateType:
      enum:
      - operational
      - degraded
      - failed
      - unknown
      type: string
    ChangeLog:
      type: object
    ResolvedConnectorView:
      allOf:
      - $ref: '#/components/schemas/EnvelopeView'
      - properties:
          actionCount:
            minimum: 0
            type: integer
          connectionDefinitionId:
            $ref: '#/components/schemas/ConnectionDefinitionId'
          imageUrl:
            type: string
          name:
            type: string
          platform:
            type: string
        required:
        - connectionDefinitionId
        - name
        - platform
        - imageUrl
        - actionCount
        type: object
    LinkInvitationView:
      properties:
        acceptedAt:
          format: date-time
          type:
          - string
          - 'null'
        active:
          type: boolean
        activity:
          items:
            $ref: '#/components/schemas/InvitationActivity'
          type: array
        branding:
          $ref: '#/components/schemas/BrandingSnapshot'
        connectorRules:
          items:
            $ref: '#/components/schemas/ConnectorRule'
          type: array
        createdAt:
          format: date-time
          type: string
        customerEmail:
          type: string
        customerName:
          type: string
        customerProjectId:
          format: uuid
          type: string
        environment:
          $ref: '#/components/schemas/SecretKeyEnvironment'
        eventAccessId:
          $ref: '#/components/schemas/EventAccessId'
        expiresAt:
          format: date-time
          type: string
        id:
          format: uuid
          type: string
        internalName:
          type: string
        lastResendAt:
          format: date-time
          type:
          - string
          - 'null'
        organizationId:
          format: uuid
          type: string
        status:
          $ref: '#/components/schemas/LinkInvitationStatusType'
        templateId:
          format: uuid
          type: string
        templateProjectId:
          format: uuid
          type:
          - string
          - 'null'
        updatedAt:
          format: date-time
          type: string
      required:
      - id
      - templateId
      - organizationId
      - customerProjectId
      - eventAccessId
      - customerName
      - customerEmail
      - internalName
      - environment
      - status
      - expiresAt
      - connectorRules
      - branding
      - activity
      - createdAt
      - updatedAt
      - active
      type: object
    PrepareInitParams:
      properties:
        group:
          type:
          - string
          - 'null'
        identity:
          type:
          - string
          - 'null'
        identityType:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/ConnectionIdentityType'
        label:
          type:
          - string
          - 'null'
        name:
          type:
          - string
          - 'null'
        tags:
          items:
            type: string
          type:
          - array
          - 'null'
      type: object
    LinkInvitationStatusType:
      enum:
      - pending
      - accepted
      - expired
      type: string
    ConnectionOAuthDefinitionId:
      description: Prefixed ID with 'conn_oauth_def' prefix (e.g., 'conn_oauth_def_1C'), also accepts raw integer
      type: string
    ConnectionDefinitionId:
      description: Prefixed ID with 'conn_def' prefix (e.g., 'conn_def_1C'), also accepts raw integer
      type: string
    ConnectionType:
      enum:
      - api
      - databasesql
      - databasenosql
      - filesystem
      - stream
      - custom
      type: string
    OAuthRequestId:
      description: Prefixed ID with 'oauth_req' prefix (e.g., 'oauth_req_1C'), also accepts raw integer
      type: string
    InitResponse:
      allOf:
      - $ref: '#/components/schemas/Paginated_ConnectedPlatformView'
      - properties:
          requestId:
            oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/OAuthRequestId'
        type: object
    ConnectionIdentityType:
      enum:
      - organization
      - user
      - team
      - project
      type: string
    RetrieveResponse:
      description: 'Retrieve response surfaces the invitation alongside the

        `connected_platforms` rows currently activated in the customer_project.

        Closes the agency''s visibility gap into auto-activation results — without

        this they have no read path to "did activation actually land for this

        invitation."'
      properties:
        activatedConnectors:
          $ref: '#/components/schemas/Paginated_ConnectedPlatformView'
        invitation:
          $ref: '#/components/schemas/LinkInvitationView'
      required:
      - invitation
      - activatedConnectors
      type: object
    ConnectorRule:
      oneOf:
      - properties:
          actionIds:
            items:
              type: string
            type:
            - array
            - 'null'
          connectionDefinitionId:
            $ref: '#/components/schemas/ConnectionDefinitionId'
          methods:
            items:
              $ref: '#/components/schemas/Method'
            type:
            - array
            - 'null'
          type:
            enum:
            - connectionDefinition
            type: string
        required:
        - connectionDefinitionId
        - type
        type: object
    RotateResponse:
      properties:
        apiKey:
          type: string
      required:
      - apiKey
      type: object
    EventAccessId:
      description: Prefixed ID with 'evt_ac' prefix (e.g., 'evt_ac_1C'), also accepts raw integer
      type: string
    Paginated_ConnectionView:
      properties:
        page:
          format: int64
          minimum: 0
          type: integer
        pages:
          format: int64
          minimum: 0
          type: integer
        rows:
          items:
            properties:
              active:
                type: boolean
              changeLog:
                $ref: '#/components/schemas/ChangeLog'
              connectionDefinitionId:
                $ref: '#/components/schemas/ConnectionDefinitionId'
              connectionOauthDefId:
                oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/ConnectionOAuthDefinitionId'
              createdAt:
                format: date-time
                type: string
              deleted:
                type: boolean
              environment:
                $ref: '#/components/schemas/SecretKeyEnvironment'
              expiresAt:
                format: date-time
                type:
                - string
                - 'null'
              expiresIn:
                format: int64
                type:
                - integer
                - 'null'
              group:
                type: string
              id:
                format: uuid
                type: string
              identity:
                type:
                - string
                - 'null'
              identityType:
                oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/ConnectionIdentityType'
              image:
                type:
                - string
                - 'null'
              key:
                type: string
              name:
                type:
                - string
                - 'null'
              platform:
                type: string
              platformVersion:
                type: string
              secretId:
                format: uuid
                type: string
              state:
                $ref: '#/components/schemas/ConnectionStateType'
              tags:
                items:
                  type: string
                type: array
              title:
                type:
                - string
                - 'null'
              type:
                $ref: '#/components/schemas/ConnectionType'
              updatedAt:
                format: date-time
                type: string
              userId:
                format: uuid
                type: string
              version:
                type: string
              webhookSecretId:
                format: uuid
                type:
                - string
                - 'null'
            required:
            - id
            - platformVersion
            - connectionDefinitionId
            - type
            - group
            - key
            - environment
            - platform
            - secretId
            - state
            - userId
            - createdAt
            - updatedAt
            - version
            - deleted
            - changeLog
            - tags
            - active
            type: object
          type: array
        total:
          format: int64
          minimum: 0
          type: integer
      required:
      - rows
      - total
      - pages
      - page
      type: object
    InvitationActivity:
      oneOf:
      - properties:
          at:
            format: date-time
            type: string
          kind:
            enum:
            - invitation_sent
            type: string
        required:
        - at
        - kind
        type: object
      - properties:
          at:
            format: date-time
            type: string
          kind:
            enum:
            - magic_link_resent
            type: string
        required:
        - at
        - kind
        type: object
      - properties:
          at:
            format: date-time
            type: string
          connection_id:
            format: uuid
            type: string
          kind:
            enum:
            - customer_connected
            type: string
          platform:
            type: string
        required:
        - at
        - platform
        - connection_id
        - kind
        type: object
      - properties:
          at:
            format: date-time
            type: string
          kind:
            enum:
            - invitation_accepted
            type: string
        required:
        - at
        - kind
        type: object
      - properties:
          at:
            format: date-time
            type: string
          kind:
            enum:
            - invitation_expired
            type: string
        required:
        - at
        - kind
        type: object
      - properties:
          at:
            format: date-time
            type: string
          by_user_id:
            format: uuid
            type: string
          kind:
            enum:
            - api_key_rotated
            type: string
        required:
        - at
        - by_user_id
        - kind
        type: object
    Paginated_ConnectedPlatformView:
      properties:
        page:
          format: int64
          minimum: 0
          type: integer
        pages:
          format: int64
          minimum: 0
          type: integer
        rows:
          items:
            properties:
              activatedAt:
                format: date-time
                type:
                - string
                - 'null'
              active:
                type: boolean
              clientIdDisplay:
                type:
                - string
                - 'null'
              clientSecretDisplay:
                type:
                - string
                - 'null'
              connectionDefId:
                $ref: '#/components/schemas/ConnectionDefinitionId'
              createdAt:
                format: date-time
                type: string
              environment:
                $ref: '#/components/schemas/SecretKeyEnvironment'
              guide:
                type:
                - string
                - 'null'
              id:
                $ref: '#/components/schemas/ConnectedPlatformId'
              image:
                type: string
              scopes:
                type:
                - string
                - 'null'
              secretId:
                format: uuid
                type:
                - string
                - 'null'
              tags:
                items:
                  type: string
                type: array
              title:
                type: string
              type:
                type: string
              useDefaultOauthCreds:
                type: boolean
            required:
            - id
            - connectionDefId
            - type
            - title
            - image
            - environment
            - createdAt
            - tags
            - active
            - useDefaultOauthCreds
            type: object
          type: array
        total:
          format: int64
          minimum: 0
          type: integer
      required:
      - rows
      - total
      - pages
      - page
      type: object
    ConnectedPlatformId:
      description: Prefixed ID with 'conn_plf' prefix (e.g., 'conn_plf_1C'), also accepts raw integer
      type: string
    ErrorResponse:
      properties:
        correlationId:
          example: 550e8400-e29b-41d4-a716-446655440000
          type: string
        key:
          example: http_error
          type: string
        message:
          example: Authentication required
          type: string
        status:
          example: 401
          format: int32
          minimum: 0
          type: integer
        type:
          example: http_error
          type: string
      required:
      - correlationId
      - key
      - message
      - type
      - status
      type: object
    SecretKeyEnvironment:
      enum:
      - test
      - live
      type: string
    ResolveResponse:
      properties:
        connectors:
          items:
            $ref: '#/components/schemas/ResolvedConnectorView'
          type: array
        invitation:
          $ref: '#/components/schemas/LinkInvitationView'
      required:
      - invitation
      - connectors
      type: object
    Method:
      enum:
      - OPTIONS
      - GET
      - POST
      - PUT
      - DELETE
      - HEAD
      - TRACE
      - CONNECT
      - PATCH
      type: string
    AllowedActionView:
      properties:
        id:
          description: 'The action''s **`system_id`**, not its row id.


            This is the identifier a rule''s `actionIds` carries and the one both

            the permission-set editor and the consent submission are validated

            against, so it is the only id a client can send back. Publishing the

            row id instead round-trips into an action that resolves to a different

            connector, which consent now refuses as foreign.'
          type: string
        title:
          type: string
      required:
      - id
      - title
      type: object
    EnvelopeView:
      description: 'What a connector rule lets through, as every surface publishes it.


        **Absent means unrestricted, on the way out and on the way back in.** A

        submission that omits `methods` asks for *every* method, so a client offered

        a narrowed connector sends this envelope back verbatim or its submission is

        refused as widening - and "copy what is there, omit what is not" therefore

        produces a valid submission in every case. Published without it, a narrowed

        offer was impossible to accept at all.


        One type rather than one per surface: the held rule and the ask it is

        bounded by are the same envelope answering the same round-trip contract, and

        two definitions of it would eventually disagree.'
      properties:
        allowedActions:
          description: 'Resolved titles for the rule''s `action_ids`, present only when the rule

            narrows to a specific set (i.e. a custom rule). `None` means every

            action on the connector, which a customer-facing UI labels

            generically rather than listing.'
          items:
            $ref: '#/components/schemas/AllowedActionView'
          type:
          - array
          - 'null'
        methods:
          items:
            $ref: '#/components/schemas/Method'
          type:
          - array
          - 'null'
      type: object
  securitySchemes:
    Bearer:
      scheme: bearer
      type: http
    OAuth2:
      flows:
        authorizationCode:
          authorizationUrl: https://api.withone.ai/oauth/authorize
          scopes:
            org:ai_skills:read: Read organization AI skills
            org:ai_skills:write: Create, update, and delete organization AI skills
            org:authkit:read: Read organization AuthKit resources
            org:authkit:write: Create, update, and delete organization AuthKit resources
            org:connections:read: Read organization connections
            org:connections:write: Create, update, and delete organization connections
            org:projects:read: Read organization projects
            org:projects:write: Create, update, and delete organization projects
            org:secrets:read: Read organization secrets
            org:secrets:write: Create, update, and delete organization secrets
            org:workflows:executions:read: Read organization workflow executions
            org:workflows:executions:write: Create, update, and delete organization workflow executions
            org:workflows:read: Read organization workflows
            org:workflows:write: Create, update, and delete organization workflows
            project:ai_skills:read: Read project AI skills
            project:ai_skills:write: Create, update, and delete project AI skills
            project:authkit:read: Read project AuthKit resources
            project:authkit:write: Create, update, and delete project AuthKit resources
            project:connections:read: Read project connections
            project:connections:write: Create, update, and delete project connections
            project:secrets:read: Read project secrets
            project:secrets:write: Create, update, and delete project secrets
            project:workflows:executions:read: Read project workflow executions
            project:workflows:executions:write: Create, update, and delete project workflow executions
            project:workflows:read: Read project workflows
            project:workflows:write: Create, update, and delete project workflows
            user:ai_skills:read: Read your personal AI skills
            user:ai_skills:write: Create, update, and delete your personal AI skills
            user:authkit:read: Read your personal AuthKit resources
            user:authkit:write: Create, update, and delete your personal AuthKit resources
            user:connections:read: Read your personal connections
            user:connections:write: Create, update, and delete your personal connections
            user:secrets:read: Read your personal secrets
            user:secrets:write: Create, update, and delete your personal secrets
            user:workflows:executions:read: Read your personal workflow executions
            user:workflows:executions:write: Create, update, and delete your personal workflow executions
            user:workflows:read: Read your personal workflows
            user:workflows:write: Create, update, and delete your personal workflows
          tokenUrl: https://api.withone.ai/oauth/token
      type: oauth2
    Session:
      in: cookie
      name: withone
      type: apiKey
    X-One-Connection-Key:
      in: header
      name: X-One-Connection-Key
      type: apiKey
    X-One-Secret:
      in: header
      name: X-One-Secret
      type: apiKey
    X-Pica-Connection-Key:
      in: header
      name: X-One-Connection-Key
      type: apiKey
    X-Pica-Secret:
      in: header
      name: X-One-Secret
      type: apiKey