parcelLab Agents API

openapi: 3.2.0
info:
  title: parcelLab Agents API
  version: v4
  description: '# API Description


    ## Overview


    Use this API to interact with the parcelLab platform. It is currently in preview. For a reference of our current API, please refer to the API documentation.


    The API v4 allows for enhanced and more standardized interaction with our platform. It does however not yet cover all of the features of our v1/v2 APIs.


    ## Authentication


    Most endpoints in this API need authentication, unless otherwise stated. The authentication is done using the `Authorization` header with the value `Parcellab-API-Token `. You can generate the token in our portal, or ask our support team for one. The token needs to be base64 encoded together with the account ID, like: `base64encode(account_id:token)`. Here is an example of how to do it in Python:


    ```python

    import base64

    base64.b64encode(b''account_id:token'').decode(''utf-8'')

    ```


    ## Errors


    The API uses standard HTTP status codes to show the success or failure of a request. In case of an error, the response body will contain a JSON object with the following structure:


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "error_code",

    "detail": "Error message.",

    "attr": "Optional additional information."

    }

    ]

    }

    ```


    ### 401 Unauthorized


    The API returns these errors with the status code 401 when the authentication fails. It also returns them when a request does not include the authentication information. Here are the 2 possible errors.


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "authentication_failed",

    "detail": "Incorrect authentication credentials.",

    "attr": null

    }

    ]

    }

    ```


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "not_authenticated",

    "detail": "Authentication credentials were not provided.",

    "attr": null

    }

    ]

    }

    ```


    ### 403 Forbidden


    The API returns this error when the authentication is correct but does not allow the request. For example, an API token with only the `read` scope gets this error on a POST. Here is how it looks:


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "permission_denied",

    "detail": "You do not have permission to perform this action.",

    "attr": null

    }

    ]

    }

    ```


    ### 405 Method Not Allowed


    The API returns this error when you call an endpoint with an unexpected HTTP method. For example, if updating a user needs a POST request and you send a PATCH instead, you get this error. Here is how it looks:


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "method_not_allowed",

    "detail": "Method “patch” not allowed.",

    "attr": null

    }

    ]

    }

    ```


    ### 406 Not Acceptable


    The API returns this error if you send an `Accept` header with a value other than `application/json`. Here is how the response would look:


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "not_acceptable",

    "detail": "Could not satisfy the request Accept header.",

    "attr": null

    }

    ]

    }

    ```


    ### 415 Unsupported Media Type


    The API returns this error when the request content type is not JSON. Here is how the response would look:


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "not_acceptable",

    "detail": "Unsupported media type “application/xml” in request.",

    "attr": null

    }

    ]

    }

    ```


    ### 500 Internal Server Error


    The API returns this error when the server encounters an unexpected error. Here is how the response would look:


    ```json

    {

    "type": "server_error",

    "errors": [

    {

    "code": "error",

    "detail": "A server error occurred.",

    "attr": null

    }

    ]

    }

    ```'
tags:
- name: Agents
paths:
  /v4/agents/{agent_id}/execute/:
    post:
      operationId: agents_execute_create
      description: Starts agent execution asynchronously and returns a thread reference immediately. Use the thread reference to poll for results.
      summary: Start async agent execution
      parameters:
      - in: path
        name: agent_id
        schema:
          type: string
          format: uuid
          description: External ID of this agent, used on the simple agent thread API
        required: true
      tags:
      - Agents
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicAgentExecuteRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PublicAgentExecuteRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PublicAgentExecuteRequest'
        required: true
      security:
      - HeaderToken: []
      - OAuth2Authentication: []
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse403'
              examples:
                PermissionDenied:
                  value:
                    type: client_error
                    errors:
                    - code: permission_denied
                      detail: You do not have permission to perform this action.
                      attr: null
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
              examples:
                NotFound:
                  value:
                    type: client_error
                    errors:
                    - code: not_found
                      detail: Not found.
                      attr: null
          description: ''
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAgentThreadResponse'
          description: ''
  /v4/agents/{agent_id}/threads/{thread_ref}/:
    get:
      operationId: agents_threads_retrieve
      description: Retrieve the current status and messages of an agent thread.
      summary: Get thread status and messages
      parameters:
      - in: query
        name: account_id
        schema:
          type: integer
        description: Execution account ID. Required for installable agents.
      - in: path
        name: agent_id
        schema:
          type: string
          format: uuid
          description: External ID of this agent, used on the simple agent thread API
        required: true
      - in: path
        name: thread_ref
        schema:
          type: string
        description: External reference ID of the thread
        required: true
      tags:
      - Agents
      security:
      - HeaderToken: []
      - OAuth2Authentication: []
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse403'
              examples:
                PermissionDenied:
                  value:
                    type: client_error
                    errors:
                    - code: permission_denied
                      detail: You do not have permission to perform this action.
                      attr: null
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
              examples:
                NotFound:
                  value:
                    type: client_error
                    errors:
                    - code: not_found
                      detail: Not found.
                      attr: null
          description: ''
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSimpleAgentThreadDetail'
          description: ''
  /v4/agents/{agent_id}/threads/{thread_ref}/messages/:
    post:
      operationId: agents_threads_messages_create
      description: Async add a new message to an existing thread.
      summary: Add message to existing thread
      parameters:
      - in: path
        name: agent_id
        schema:
          type: string
          format: uuid
          description: External ID of this agent, used on the simple agent thread API
        required: true
      - in: path
        name: thread_ref
        schema:
          type: string
        description: External reference ID of the thread
        required: true
      tags:
      - Agents
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicAgentExecuteRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PublicAgentExecuteRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PublicAgentExecuteRequest'
        required: true
      security:
      - HeaderToken: []
      - OAuth2Authentication: []
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse403'
              examples:
                PermissionDenied:
                  value:
                    type: client_error
                    errors:
                    - code: permission_denied
                      detail: You do not have permission to perform this action.
                      attr: null
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
              examples:
                NotFound:
                  value:
                    type: client_error
                    errors:
                    - code: not_found
                      detail: Not found.
                      attr: null
          description: ''
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAgentThreadResponse'
          description: ''
components:
  schemas:
    GenericErrorItem:
      type: object
      properties:
        code:
          type: string
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - code
      - detail
    OutputAttachment:
      properties:
        id:
          title: Id
          type: integer
        name:
          title: Name
          type: string
        content_type:
          title: Content Type
          type: string
        byte_size:
          maximum: 52428800
          minimum: 0
          title: Byte Size
          type: integer
        workspace_path:
          title: Workspace Path
          type: string
      required:
      - id
      - name
      - content_type
      - byte_size
      - workspace_path
      title: OutputAttachment
      type: object
    TaxonomyClassification:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        account:
          type: integer
          readOnly: true
        thread:
          type: integer
          readOnly: true
          description: Source thread that was classified.
        threadExternalReferenceId:
          type: string
          readOnly: true
        taxonomyAgent:
          type: integer
          readOnly: true
          description: Agent owning the taxonomy tree the category belongs to (the classified corpus's source agent).
        taxonomyAgentKey:
          type: string
          readOnly: true
        category:
          type: integer
          readOnly: true
          description: Selected taxonomy category.
        categoryCode:
          type: string
          readOnly: true
        categoryName:
          type: string
          readOnly: true
        classifierThread:
          type:
          - integer
          - 'null'
          readOnly: true
          description: Nested taxonomy-agent thread that produced this classification.
        classifierThreadExternalReferenceId:
          type:
          - string
          - 'null'
          readOnly: true
        confidence:
          type:
          - number
          - 'null'
          format: double
          readOnly: true
        rationale:
          type: string
          readOnly: true
        rawResult:
          type: object
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
      required:
      - account
      - category
      - categoryCode
      - categoryName
      - classifierThread
      - classifierThreadExternalReferenceId
      - confidence
      - createdAt
      - id
      - rationale
      - rawResult
      - taxonomyAgent
      - taxonomyAgentKey
      - thread
      - threadExternalReferenceId
      - updatedAt
    ClientErrorEnum:
      enum:
      - client_error
      type: string
      description: '* `client_error` - Client Error'
    KindEnum:
      enum:
      - user
      - handover_continuation
      type: string
    OutputMessageTypeEnum:
      enum:
      - response
      - rejection
      type: string
    ReasoningLevel:
      enum:
      - 'off'
      - low
      - medium
      - high
      - xhigh
      title: ReasoningLevel
      type: string
    Error400Response:
      type: object
      properties:
        type:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/GenericErrorItem'
      required:
      - errors
      - type
    OutputMessage:
      properties:
        created_at:
          format: date-time
          title: Created At
          type: string
        input_message_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Input Message Id
        id:
          title: Id
          type: string
        type:
          allOf:
          - $ref: '#/components/schemas/OutputMessageTypeEnum'
          default: response
          title: Type
        response:
          title: Response
          type: string
        data:
          additionalProperties: true
          default: {}
          title: Data
          type: object
        attachments:
          items:
            $ref: '#/components/schemas/OutputAttachment'
          maxItems: 20
          title: Attachments
          type: array
      required:
      - response
      title: OutputMessage
      type: object
    SimpleAgentThreadVisibilityEnum:
      enum:
      - private
      - account_read
      - account_write
      type: string
      description: '* `private` - Private

        * `account_read` - Account read

        * `account_write` - Account write'
    PublicInputMessage:
      properties:
        created_at:
          format: date-time
          title: Created At
          type: string
        input_message_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Input Message Id
        id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Id
        type:
          const: input_message
          default: input_message
          title: Type
          type: string
        kind:
          allOf:
          - $ref: '#/components/schemas/KindEnum'
          default: user
          title: Kind
        target_agent_id:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Target Agent Id
        reasoning_effort:
          anyOf:
          - $ref: '#/components/schemas/ReasoningLevel'
          - type: 'null'
          default: null
        context:
          additionalProperties: true
          title: Context
          type: object
        query:
          title: Query
          type: string
        attachments:
          items:
            $ref: '#/components/schemas/InputAttachment'
          maxItems: 20
          title: Attachments
          type: array
      required:
      - query
      title: PublicInputMessage
      type: object
    ErrorCode403Enum:
      enum:
      - permission_denied
      type: string
      description: '* `permission_denied` - Permission Denied'
    ExecutionStatusEnum:
      enum:
      - idle
      - running
      - completed
      - failed
      type: string
      description: '* `idle` - Idle

        * `running` - Running

        * `completed` - Completed

        * `failed` - Failed'
    Error404:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode404Enum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
    PublicSimpleAgentThreadDetail:
      type: object
      description: Public-facing thread details with limited message info.
      properties:
        id:
          type: integer
          readOnly: true
        title:
          type: string
          readOnly: true
        visibility:
          allOf:
          - $ref: '#/components/schemas/SimpleAgentThreadVisibilityEnum'
          readOnly: true
        externalReferenceId:
          type: string
          readOnly: true
        account:
          type: integer
        agent:
          type: string
          format: uuid
          description: External ID of this agent, used on the simple agent thread API
        currentAgent:
          type: string
          format: uuid
          description: External ID of this agent, used on the simple agent thread API
          readOnly: true
        user:
          type: integer
          readOnly: true
        executionStatus:
          $ref: '#/components/schemas/ExecutionStatusEnum'
        taxonomyClassification:
          oneOf:
          - $ref: '#/components/schemas/TaxonomyClassification'
          - type: 'null'
          readOnly: true
        contentType:
          type:
          - string
          - 'null'
          title: Python model class name
          description: Lowercased Django model name of the linked object (e.g. 'layout', 'tracking'). Pair with object_id.
        objectId:
          type: string
          maxLength: 255
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        messages:
          items:
            anyOf:
            - $ref: '#/components/schemas/PublicInputMessage'
            - $ref: '#/components/schemas/OutputMessage'
          type: array
        progressText:
          type: string
          readOnly: true
        progressReasoning:
          type: string
          readOnly: true
        stream:
          type: object
          properties:
            enabled:
              type: boolean
            interactive:
              type: boolean
            status:
              enum:
              - unavailable
              - pending
              - active
              type: string
            expectedInputId:
              type: string
              nullable: true
            websocketUrl:
              type: string
              nullable: true
            endpointToken:
              type: string
              nullable: true
            workspaceFileUrl:
              type: string
              nullable: true
            expiresAt:
              type: string
              nullable: true
          required:
          - enabled
          - endpointToken
          - expectedInputId
          - expiresAt
          - interactive
          - status
          - websocketUrl
          - workspaceFileUrl
          readOnly: true
      required:
      - account
      - agent
      - createdAt
      - currentAgent
      - externalReferenceId
      - id
      - messages
      - progressReasoning
      - progressText
      - stream
      - taxonomyClassification
      - title
      - updatedAt
      - user
      - visibility
    ErrorResponse403:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ClientErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error403'
      required:
      - errors
      - type
    PublicAgentExecuteRequest:
      type: object
      description: Payload for starting async agent execution.
      properties:
        account_id:
          type: integer
          description: Execution account ID. Required for installable agents.
        query:
          type: string
          minLength: 1
          description: The user's input query
        context:
          type: object
          description: Optional context data for the agent
      required:
      - query
    ErrorResponse404:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ClientErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error404'
      required:
      - errors
      - type
    InputAttachment:
      properties:
        id:
          title: Id
          type: integer
        name:
          title: Name
          type: string
        content_type:
          title: Content Type
          type: string
        byte_size:
          maximum: 52428800
          minimum: 0
          title: Byte Size
          type: integer
      required:
      - id
      - name
      - content_type
      - byte_size
      title: InputAttachment
      type: object
    Error403:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode403Enum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
    ErrorCode404Enum:
      enum:
      - not_found
      type: string
      description: '* `not_found` - Not Found'
    PublicAgentThreadResponse:
      type: object
      description: Response for async agent execution.
      properties:
        threadId:
          type: string
          description: External reference ID of the thread
        currentAgent:
          type: string
          format: uuid
          description: External ID of the agent currently responsible for the thread
          readOnly: true
        executionStatus:
          type: string
          description: Current execution status
      required:
      - currentAgent
      - executionStatus
      - threadId
  securitySchemes:
    HeaderToken:
      type: apiKey
      in: header
      name: Authorization
      x-gitbook-prefix: Parcellab-API-Token
      x-gitbook-token-placeholder: YOUR_BASE64_ENCODED_API_TOKEN
      description: 'Send `Authorization: Parcellab-API-Token <encoded-token>`.


        `<encoded-token>` = `base64(account_id:token)` as provided in the portal.'
    OAuth2Authentication:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Unbound access tokens use Authorization: Bearer <token>. DPoP-bound tokens use Authorization: DPoP <token> and a DPoP proof header signed with the bound key for each request. Supported proof algorithms: ES256 and RS256.'