Archastro Threads API

openapi: 3.0.0
info:
  description: Agent-first API for runtime + developer control-plane operations (users, teams, agents, routines, context, workflows, integrations, and webhooks).
  title: ArchAstro Platform Activity Feed Threads API
  version: v1
tags:
- name: Threads
paths:
  /api/v1/threads/{thread}:
    delete:
      description: 'Permanently deletes a thread and all of its messages and artifacts. This action

        cannot be undone.


        The authenticated user must own the thread or be an owner of the team the thread

        belongs to. Attempting to delete a thread owned by another user or team returns 403.'
      operationId: delete_api_v1_threads__thread
      parameters:
      - description: Thread ID (`thr_...`). The authenticated user must own this thread.
        example: string
        in: path
        name: thread
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No content
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Thread not found
      summary: Delete a thread
      x-auth:
      - bearer
      - publishable_key
      tags:
      - Threads
    get:
      description: 'Returns the full thread record for the given thread ID. The authenticated user

        must own the thread or be a member of the workspace it belongs to.


        Use this endpoint to fetch the current state of a single thread, including its

        title, description, and metadata. To list many threads, use the list endpoint

        with cursor-based pagination.'
      operationId: get_api_v1_threads__thread
      parameters:
      - description: Thread ID (`thr_...`). The authenticated user must have access to this thread.
        example: string
        in: path
        name: thread
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thread'
          description: Successful response
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Thread not found
      summary: Retrieve a thread
      x-auth:
      - bearer
      - publishable_key
      tags:
      - Threads
    put:
      description: 'Updates one or more mutable properties of the specified thread and returns

        the full thread object with the applied changes. Only the fields you provide

        are modified; omitted fields retain their current values.


        If `profile_picture` is supplied, the image is uploaded before the other

        fields are saved. Supplying invalid base64 picture data returns 422 and no

        other fields are updated.


        The authenticated user must own the thread or be a team owner of the workspace

        the thread belongs to.'
      operationId: put_api_v1_threads__thread
      parameters:
      - description: Thread ID (`thr_...`). The authenticated user must have permission to update this thread.
        example: string
        in: path
        name: thread
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              example:
                description: An example description.
                metadata:
                  key: value
                muted: true
                profile_picture:
                  data: string
                  filename: string
                  mime_type: application/json
                title: Example Title
              properties:
                description:
                  description: Optional longer text describing the thread's purpose. Replaces the existing description when provided.
                  example: An example description.
                  type: string
                metadata:
                  description: Arbitrary key-value metadata to store on the thread. Merged with or replaces existing metadata.
                  example:
                    key: value
                  type: object
                muted:
                  description: When `true`, suppresses notifications for new messages in this thread for the authenticated user.
                  example: true
                  type: boolean
                profile_picture:
                  description: New profile picture for the thread. Provide all three inner fields to replace the existing image.
                  example:
                    data: string
                    filename: string
                    mime_type: application/json
                  properties:
                    data:
                      description: Base64-encoded image payload. Must be a valid base64 string.
                      example: string
                      type: string
                    filename:
                      description: Original filename of the image, e.g. `"avatar.png"`. Used for storage metadata.
                      example: string
                      type: string
                    mime_type:
                      description: MIME type of the image, e.g. `"image/jpeg"` or `"image/png"`.
                      example: application/json
                      type: string
                  type: object
                title:
                  description: Human-readable display name for the thread. Replaces the existing title when provided.
                  example: Example Title
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thread'
          description: Successful response
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Thread not found
        '422':
          description: Validation failed
      summary: Update a thread
      x-auth:
      - bearer
      - publishable_key
      tags:
      - Threads
  /api/v1/threads/{thread}/agents:
    get:
      description: 'Returns the agents participating in the specified thread. Only personal user

        threads (threads owned by a single user, not a team) expose agents through

        this endpoint; requests for team threads return 404.


        The authenticated user must have visibility into the thread. Each agent entry

        includes display information such as name and profile picture. Thread-level

        overrides (e.g. a custom name or profile picture set for this thread) take

        precedence over the agent''s default values. When the caller is the thread

        owner, each entry also includes an `agent_config` object describing the

        agent''s message policy and context configuration.'
      operationId: get_api_v1_threads__thread_agents
      parameters:
      - description: Thread ID (`thr_...`). Must be a personal user thread visible to the authenticated user.
        example: string
        in: path
        name: thread
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                description: The list of agents participating in the thread.
                example:
                  data:
                  - {}
                properties:
                  data:
                    description: Array of agent objects for the thread. Each object includes `id`, `name`, `alias`, `profile_picture`, and `metadata`. Thread owners also receive an `agent_config` object with the agent's policy type and context configuration.
                    example:
                    - {}
                    items:
                      type: object
                    type: array
                required:
                - data
                type: object
          description: Successful response
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Thread not found
      summary: List agents in a thread
      x-auth:
      - bearer
      - publishable_key
      tags:
      - Threads
  /api/v1/threads/{thread}/artifacts:
    get:
      description: 'Returns all artifacts produced during a thread''s AI conversation. Artifacts are

        structured outputs such as code files, documents, or generated assets created

        by the AI agent in response to messages in the thread.


        The authenticated user must have access to the specified thread. Results are

        returned in a single page; there is no cursor-based pagination for this endpoint.'
      operationId: get_api_v1_threads__thread_artifacts
      parameters:
      - description: Thread ID (`thr_...`). Must be accessible to the authenticated user.
        example: string
        in: path
        name: thread
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Artifact listing for the thread.
                example:
                  data:
                  - agent: agt_0aBcDeFgHiJkLmNoPqRsTu
                    content_type: application/json
                    created_at: '2024-01-01T00:00:00Z'
                    current_version: afv_0aBcDeFgHiJkLmNoPqRsTu
                    description: An example description.
                    file: string
                    file_name: Example Name
                    file_url: https://example.com
                    id: art_0aBcDeFgHiJkLmNoPqRsTu
                    image_source:
                      file: fil_0aBcDeFgHiJkLmNoPqRsTu
                      height: 600
                      media: med_0aBcDeFgHiJkLmNoPqRsTu
                      mime_type: application/json
                      refresh_url: https://example.com
                      url: https://example.com
                      width: 800
                    name: Example Name
                    org: org_0aBcDeFgHiJkLmNoPqRsTu
                    sandbox: string
                    team: tem_0aBcDeFgHiJkLmNoPqRsTu
                    thread: thr_0aBcDeFgHiJkLmNoPqRsTu
                    updated_at: '2024-01-01T00:00:00Z'
                    user: usr_0aBcDeFgHiJkLmNoPqRsTu
                    version: 1
                properties:
                  data:
                    description: Array of artifact objects produced during the thread's conversation.
                    example:
                    - agent: agt_0aBcDeFgHiJkLmNoPqRsTu
                      content_type: application/json
                      created_at: '2024-01-01T00:00:00Z'
                      current_version: afv_0aBcDeFgHiJkLmNoPqRsTu
                      description: An example description.
                      file: string
                      file_name: Example Name
                      file_url: https://example.com
                      id: art_0aBcDeFgHiJkLmNoPqRsTu
                      image_source:
                        file: fil_0aBcDeFgHiJkLmNoPqRsTu
                        height: 600
                        media: med_0aBcDeFgHiJkLmNoPqRsTu
                        mime_type: application/json
                        refresh_url: https://example.com
                        url: https://example.com
                        width: 800
                      name: Example Name
                      org: org_0aBcDeFgHiJkLmNoPqRsTu
                      sandbox: string
                      team: tem_0aBcDeFgHiJkLmNoPqRsTu
                      thread: thr_0aBcDeFgHiJkLmNoPqRsTu
                      updated_at: '2024-01-01T00:00:00Z'
                      user: usr_0aBcDeFgHiJkLmNoPqRsTu
                      version: 1
                    items:
                      description: A versioned artifact produced or managed by an agent, such as a generated file, report, or code output.
                      example:
                        agent: agt_0aBcDeFgHiJkLmNoPqRsTu
                        content_type: application/json
                        created_at: '2024-01-01T00:00:00Z'
                        current_version: afv_0aBcDeFgHiJkLmNoPqRsTu
                        description: An example description.
                        file: string
                        file_name: Example Name
                        file_url: https://example.com
                        id: art_0aBcDeFgHiJkLmNoPqRsTu
                        image_source:
                          file: fil_0aBcDeFgHiJkLmNoPqRsTu
                          height: 600
                          media: med_0aBcDeFgHiJkLmNoPqRsTu
                          mime_type: application/json
                          refresh_url: https://example.com
                          url: https://example.com
                          width: 800
                        name: Example Name
                        org: org_0aBcDeFgHiJkLmNoPqRsTu
                        sandbox: string
                        team: tem_0aBcDeFgHiJkLmNoPqRsTu
                        thread: thr_0aBcDeFgHiJkLmNoPqRsTu
                        updated_at: '2024-01-01T00:00:00Z'
                        user: usr_0aBcDeFgHiJkLmNoPqRsTu
                        version: 1
                      properties:
                        agent:
                          description: ID of the agent that produced this artifact (`agt_...`). `null` if not agent-produced.
                          example: agt_0aBcDeFgHiJkLmNoPqRsTu
                          type: string
                        content_type:
                          description: MIME type of the current version's file, e.g. `"text/csv"` or `"image/png"`. `null` if no file is attached.
                          example: application/json
                          type: string
                        created_at:
                          description: When the artifact was first created (ISO 8601).
                          example: '2024-01-01T00:00:00Z'
                          format: date-time
                          type: string
                        current_version:
                          description: ID of the current (latest published) artifact version (`artv_...`). `null` if no version has been published.
                          example: afv_0aBcDeFgHiJkLmNoPqRsTu
                          type: string
                        description:
                          description: Optional longer description of the artifact's contents or purpose. `null` if not set.
                          example: An example description.
                          type: string
                        file:
                          description: Storage file ID for the current version (`fil_...`). `null` if no file is attached.
                          example: string
                          type: string
                        file_name:
                          description: Original filename of the current version's file, e.g. `"output.csv"`. `null` if no file is attached.
                          example: Example Name
                          type: string
                        file_url:
                          description: Short-lived signed URL for downloading the current version's file. `null` if no file is attached.
                          example: https://example.com
                          type: string
                        id:
                          description: Artifact ID (`art_...`).
                          example: art_0aBcDeFgHiJkLmNoPqRsTu
                          type: string
                        image_source:
                          description: Image source metadata for rendering the current version's file inline. Present only when `content_type` starts with `"image/"`. `null` otherwise.
                          example:
                            file: fil_0aBcDeFgHiJkLmNoPqRsTu
                            height: 600
                            media: med_0aBcDeFgHiJkLmNoPqRsTu
                            mime_type: application/json
                            refresh_url: https://example.com
                            url: https://example.com
                            width: 800
                          properties:
                            file:
                              description: ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.
                              example: fil_0aBcDeFgHiJkLmNoPqRsTu
                              type: string
                            height:
                              description: Height of the image in pixels. `null` if not known.
                              example: 600
                              type: integer
                            media:
                              description: ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.
                              example: med_0aBcDeFgHiJkLmNoPqRsTu
                              type: string
                            mime_type:
                              description: MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.
                              example: application/json
                              type: string
                            refresh_url:
                              description: Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.
                              example: https://example.com
                              type: string
                            url:
                              description: Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.
                              example: https://example.com
                              type: string
                            width:
                              description: Width of the image in pixels. `null` if not known.
                              example: 800
                              type: integer
                          type: object
                        name:
                          description: Human-readable name for the artifact, e.g. `"Q2 Report"`. `null` if not set.
                          example: Example Name
                          type: string
                        org:
                          description: ID of the organization this artifact belongs to (`org_...`).
                          example: org_0aBcDeFgHiJkLmNoPqRsTu
                          type: string
                        sandbox:
                          description: Identifier of the sandbox environment associated with this artifact. `null` if not sandbox-scoped.
                          example: string
                          type: string
                        team:
                          description: ID of the team that owns this artifact (`tea_...`). `null` if not team-scoped.
                          example: tem_0aBcDeFgHiJkLmNoPqRsTu
                          type: string
                        thread:
                          description: ID of the thread in which this artifact was created (`thr_...`). `null` if not thread-scoped.
                          example: thr_0aBcDeFgHiJkLmNoPqRsTu
                          type: string
                        updated_at:
                          description: When the artifact record was last modified (ISO 8601).
                          example: '2024-01-01T00:00:00Z'
                          format: date-time
                          type: string
                        user:
                          description: ID of the user who created this artifact (`usr_...`). `null` if not user-scoped.
                          example: usr_0aBcDeFgHiJkLmNoPqRsTu
                          type: string
                        version:
                          description: Current version number of the artifact. Increments each time a new version is published.
                          example: 1
                          type: integer
                      required:
                      - id
                      type: object
                    type: array
                required:
                - data
                type: object
          description: Successful response
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Thread not found
      summary: List artifacts for a thread
      x-auth:
      - bearer
      - publishable_key
      tags:
      - Threads
  /api/v1/threads/{thread}/mark_read:
    post:
      description: 'Records that a user has read up to a specific message in the thread. Unread

        indicators and badge counts are cleared up to the specified message.


        You must supply exactly one of `last_read_message` or `use_latest_message`.

        Omitting both returns 400. If `use_latest_message` is `true` and the thread

        has no messages, the request succeeds silently with no state change.


        For server-to-server (S2S) requests where no user identity is present in the

        token, the `user` param is required to identify whose read state to update.'
      operationId: post_api_v1_threads__thread_mark_read
      parameters:
      - description: Thread ID (`thr_...`). The thread to mark as read.
        example: string
        in: path
        name: thread
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              example:
                last_read_message: string
                use_latest_message: true
                user: string
              properties:
                last_read_message:
                  description: Message ID (`msg_...`) to record as the last read message. Mutually exclusive with `use_latest_message`.
                  example: string
                  type: string
                use_latest_message:
                  description: When `true`, marks the thread as read up to the latest message. Mutually exclusive with `last_read_message`.
                  example: true
                  type: boolean
                user:
                  description: User ID (`usr_...`) whose read state to update. Required for S2S requests; ignored when an authenticated user is present in the token.
                  example: string
                  type: string
              type: object
        required: true
      responses:
        '204':
          description: No content
        '401':
          description: Unauthorized
        '404':
          description: Thread not found
        '422':
          description: Validation error
      summary: Mark a thread as read
      x-auth:
      - bearer
      - publishable_key
      tags:
      - Threads
  /api/v1/threads/{thread}/members:
    delete:
      description: 'Removes a user or agent membership from the specified thread. The authenticated

        user must have access to the thread. A successful removal returns HTTP 204 with

        no response body.


        Supply either `user` or `agent` depending on the value of `type`. Returns 404

        if the thread or the membership record does not exist.'
      operationId: delete_api_v1_threads__thread_members
      parameters:
      - description: Thread ID (`thr_...`) identifying the thread to remove the member from.
        example: string
        in: path
        name: thread
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No content
        '401':
          description: Unauthorized
        '404':
          description: Thread or member not found
        '422':
          description: Failed to remove member
      summary: Remove a member from a thread
      x-auth:
      - bearer
      - publishable_key
      tags:
      - Threads
    get:
      description: 'Returns all current members of the specified thread, including both user and

        agent members. The authenticated user must have visibility into the thread;

        requests from users without access return 403.


        Results are returned as a flat array in the `data` field. The list is not

        paginated — all members are returned in a single response.'
      operationId: get_api_v1_threads__thread_members
      parameters:
      - description: Thread ID (`thr_...`) whose members should be returned.
        example: string
        in: path
        name: thread
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Object containing the thread's membership list.
                example:
                  data:
                  - membership_type: member
                    thread: thr_0aBcDeFgHiJkLmNoPqRsTu
                    user:
                      alias: jdoe
                      app: dap_0aBcDeFgHiJkLmNoPqRsTu
                      app_name: Example Name
                      email: user@example.com
                      id: usr_0aBcDeFgHiJkLmNoPqRsTu
                      is_system_user: true
                      metadata:
                        key: value
                      name: Example Name
                      org: org_0aBcDeFgHiJkLmNoPqRsTu
                      org_name: Example Name
                      org_role: member
                      sandbox: dsb_0aBcDeFgHiJkLmNoPqRsTu
                      sandbox_name: Example Name
                properties:
                  data:
                    description: Array of thread member objects representing all current members of the thread.
                    example:
                    - membership_type: member
                      thread: thr_0aBcDeFgHiJkLmNoPqRsTu
                      user:
                        alias: jdoe
                        app: dap_0aBcDeFgHiJkLmNoPqRsTu
                        app_name: Example Name
                        email: user@example.com
                        id: usr_0aBcDeFgHiJkLmNoPqRsTu
                        is_system_user: true
                        metadata:
                          key: value
                        name: Example Name
                        org: org_0aBcDeFgHiJkLmNoPqRsTu
                        org_name: Example Name
                        org_role: member
                        sandbox: dsb_0aBcDeFgHiJkLmNoPqRsTu
                        sandbox_name: Example Name
                    items:
                      description: A user's membership record in a thread, capturing their role and full user profile.
                      example:
                        membership_type: member
                        thread: thr_0aBcDeFgHiJkLmNoPqRsTu
                        user:
                          alias: jdoe
                          app: dap_0aBcDeFgHiJkLmNoPqRsTu
                          app_name: Example Name
                          email: user@example.com
                          id: usr_0aBcDeFgHiJkLmNoPqRsTu
                          is_system_user: true
                          metadata:
                            key: value
                          name: Example Name
                          org: org_0aBcDeFgHiJkLmNoPqRsTu
                          org_name: Example Name
                          org_role: member
                          sandbox: dsb_0aBcDeFgHiJkLmNoPqRsTu
                          sandbox_name: Example Name
                      properties:
                        membership_type:
                          description: Role of the member within the thread. One of `"owner"` (the user who created or was granted ownership) or `"member"` (a regular participant).
                          example: member
                          type: string
                        thread:
                          description: ID of the thread this membership belongs to (`thr_...`).
                          example: thr_0aBcDeFgHiJkLmNoPqRsTu
                          type: string
                        user:
                          description: Full user object for the member (`usr_...`). Present when the association is preloaded; `null` otherwise.
                          example:
                            alias: jdoe
                            app: dap_0aBcDeFgHiJkLmNoPqRsTu
                            app_name: Example Name
                            email: user@example.com
                            id: usr_0aBcDeFgHiJkLmNoPqRsTu
                            is_system_user: true
                            metadata:
                              key: value
                            name: Example Name
                            org: org_0aBcDeFgHiJkLmNoPqRsTu
                            org_name: Example Name
                            org_role: member
                            sandbox: dsb_0aBcDeFgHiJkLmNoPqRsTu
                            sandbox_name: Example Name
                          properties:
                            alias:
                              description: Short handle or alias for the user. `null` if not set.
                              example: jdoe
                              type: string
                            app:
                              description: ID of the app this user (and their access token) is scoped to (`dap_...`). `null` if the user is not scoped to an app.
                              example: dap_0aBcDeFgHiJkLmNoPqRsTu
                              type: string
                            app_name:
                              description: Display name of the user's app. `null` when the app association was not preloaded by the caller.
                              example: Example Name
                              type: string
                            email:
                              description: Email address of the user.
                              example: user@example.com
                              type: string
                            id:
                              description: User ID (`usr_...`).
                              example: usr_0aBcDeFgHiJkLmNoPqRsTu
                              type: string
                            is_system_user:
                              description: '`true` if this account is an internal system user rather than a human. System users are created automatically by the platform.'
                              example: true
                              type: boolean
                            metadata:
                              description: Arbitrary key-value metadata attached to the user. Defaults to an empty object.
                              example:
                                key: value
                              type: object
                            name:
                              description: Full display name of the user. `null` if the user has not set a name.
                              example: Example Name
                              type: string
                            org:
                              description: ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.
                              example: org_0aBcDeFgHiJkLmNoPqRsTu
                              type: string
                            org_name:
                              description: Display name of the user's organization. `null` when the user is not in an org, or when the org association was not preloaded by the caller.
                              example: Example Name
                              type: string
                            org_role:
                              description: Role of the user within their organization. One of `"admin"`, `"member"`, or `"viewer"`. `null` when the user is not a member of any organization.
                              example: member
                              type: string
                            sandbox:
                              description: ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.
                              example: dsb_0aBcDeFgHiJkLmNoPqRsTu
                              type: string
                          

# --- truncated at 32 KB (1164 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/archastro/refs/heads/main/openapi/archastro-threads-api-openapi.yml