Archastro Files API

openapi: 3.2.0
info:
  description: Agent-first API for runtime + developer control-plane operations (users, teams, agents, routines, context, workflows, integrations, and webhooks).
  title: ArchAstro Platform Files API
  version: v1
tags:
- name: Files
paths:
  /api/v1/files:
    post:
      description: 'Creates a new file from base64-encoded content and returns the resulting file object,

        including a signed download URL. Use this endpoint to store images, documents, or

        other binary assets that can then be referenced by agents, teams, or users.


        App scope is derived from the authenticated viewer''s bearer token or publishable key.

        You may optionally associate the file with an organization, team, user, or agent by

        passing the corresponding ID. If no owner is specified and the viewer is a user, the

        file is automatically attributed to that user.


        Returns `422` when the `data` field is not valid base64 or the changeset is invalid.

        Returns `403` when the request lacks the required app scope.'
      operationId: post_api_v1_files
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              example:
                agent: string
                content_type: application/json
                data: string
                filename: string
                org: string
                team: string
                user: string
              properties:
                agent:
                  description: Agent ID (`agi_...`) to associate with this file. When provided, the file's organization is derived from the agent.
                  example: string
                  type: string
                content_type:
                  description: MIME type of the file, e.g. `"image/png"` or `"application/pdf"`.
                  example: application/json
                  type: string
                data:
                  description: Base64-encoded binary content of the file to upload.
                  example: string
                  type: string
                filename:
                  description: Original filename including extension, e.g. `"avatar.png"`.
                  example: string
                  type: string
                org:
                  description: Organization ID (`org_...`) to associate with this file. Optional; defaults to the viewer's organization when omitted.
                  example: string
                  type: string
                team:
                  description: Team ID (`tem_...`) that owns this file. Takes precedence over `user` when both are provided.
                  example: string
                  type: string
                user:
                  description: User ID (`usr_...`) that owns this file. Defaults to the authenticated user when neither `user` nor `team` is specified.
                  example: string
                  type: string
              required:
              - content_type
              - data
              - filename
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageFile'
          description: Successful response
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - app scope required
        '422':
          description: Validation failed or invalid base64
      summary: Upload a file
      x-auth:
      - bearer
      - publishable_key
      tags:
      - Files
  /api/v1/files/{file}/avatar:
    get:
      description: 'Returns the raw image bytes for an agent''s profile picture identified by `file`.

        This endpoint is designed for integration partners (such as Slack) that fetch

        avatar URLs via plain GET requests without bearer token support. Authorization

        is performed via a short, stable capability `token` rather than an HTTP header.


        The `token` is an HMAC-based capability tied to the file ID. It does not expire,

        but it is invalidated when the agent''s profile picture is replaced or the agent is

        deleted — shared caches may continue serving the old image until the

        `Cache-Control` max-age of one hour elapses. The endpoint never redirects to

        a signed storage URL; bytes are served inline so behavior is consistent across

        storage backends.


        All failure modes — invalid file ID, invalid token, file not currently referenced

        as an agent avatar — return a uniform `404` to avoid acting as an existence oracle.'
      operationId: get_api_v1_files__file_avatar
      parameters:
      - description: File ID of the agent's profile picture (`fil_...`). Must be currently set as an agent's profile picture within the same app.
        example: string
        in: path
        name: file
        required: true
        schema:
          type: string
      - description: HMAC capability token authorizing access to this specific file. Obtained from the avatar URL minted when the profile picture was set.
        example: string
        in: query
        name: token
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            '*/*':
              schema:
                format: binary
                type: string
          description: Raw image bytes of the agent avatar, served with the file's original content type.
        '404':
          description: Not found
      summary: Fetch an agent avatar image
      tags:
      - Files
components:
  schemas:
    StorageFile:
      description: A file stored in the platform's object storage, with metadata and a signed URL for downloading its contents.
      example:
        content_type: application/json
        created_at: '2024-01-01T00:00:00Z'
        filename: document.pdf
        id: fil_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
        org: org_0aBcDeFgHiJkLmNoPqRsTu
        sandbox: dsb_0aBcDeFgHiJkLmNoPqRsTu
        size: 1024
        updated_at: '2024-01-01T00:00:00Z'
        url: https://example.com
      properties:
        content_type:
          description: MIME type of the file, e.g. `"image/png"` or `"application/pdf"`.
          example: application/json
          type: string
        created_at:
          description: When the file was uploaded (ISO 8601).
          example: '2024-01-01T00:00:00Z'
          format: date-time
          type: string
        filename:
          description: Original filename as provided at upload time.
          example: document.pdf
          type: string
        id:
          description: File ID (`fil_...`).
          example: fil_0aBcDeFgHiJkLmNoPqRsTu
          type: string
        image_source:
          $ref: '#/components/schemas/ImageSource'
          description: Image display metadata. Present only when `content_type` is an image type; `null` otherwise.
        org:
          description: ID of the organization that owns this file (`org_...`).
          example: org_0aBcDeFgHiJkLmNoPqRsTu
          type: string
        sandbox:
          description: ID of the sandbox this file is scoped to (`sbx_...`). `null` for files not associated with a sandbox.
          example: dsb_0aBcDeFgHiJkLmNoPqRsTu
          type: string
        size:
          description: Size of the file in bytes.
          example: 1024
          type: integer
        updated_at:
          description: When the file record was last modified (ISO 8601).
          example: '2024-01-01T00:00:00Z'
          format: date-time
          type: string
        url:
          description: Short-lived signed URL for downloading the file. `null` if a URL could not be generated.
          example: https://example.com
          type: string
      required:
      - id
      type: object
    ImageSource:
      description: Resolved metadata for an image, including its delivery URL, dimensions, and optional references to the underlying storage file or media record.
      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
x-archastro-docs-scope: external
x-auth-schemes:
  bearer:
    description: User JWT in Authorization header
    scheme: bearer
    type: http
  device_flow:
    description: Third-party device flow token — requires per-action opt-in
    scheme: bearer
    type: http
    x-token-use: third_party
  publishable_key:
    description: Publishable API key — identifies the app
    in: header
    name: x-archastro-api-key
    prefix: pk_
    type: api_key
  secret_key:
    description: Secret API key — full admin access, no user JWT required
    in: header
    name: x-archastro-api-key
    prefix: sk_
    type: api_key
x-channel-auth:
- bearer
x-channels:
- description: 'Channel for real-time chat messaging.


    Supports team-scoped and user-scoped threads with keyed, transient, and direct

    thread access patterns.'
  joins:
  - description: Join a team-scoped thread by ID
    name: join_team_thread
    params:
      example:
        after_cursor: string
        before_cursor: string
        include_metadata: true
        limit: 1
        team_id: string
        thread_id: string
      properties:
        after_cursor:
          example: string
          type: string
        before_cursor:
          example: string
          type: string
        include_metadata:
          example: true
          type: boolean
        limit:
          example: 1
          type: integer
        team_id:
          example: string
          type: string
        thread_id:
          example: string
          type: string
      required:
      - team_id
      - thread_id
      type: object
    pattern: api:chat:team:{team_id}:thread:{thread_id}
    returns:
      type: object
  - description: Join a team-scoped transient (ephemeral) thread
    name: join_team_transient
    params:
      example:
        after_cursor: string
        before_cursor: string
        include_metadata: true
        key: string
        limit: 1
        team_id: string
      properties:
        after_cursor:
          example: string
          type: string
        before_cursor:
          example: string
          type: string
        include_metadata:
          example: true
          type: boolean
        key:
          example: string
          type: string
        limit:
          example: 1
          type: integer
        team_id:
          example: string
          type: string
      required:
      - key
      - team_id
      type: object
    pattern: api:chat:team:{team_id}:transient:{key}
    returns:
      type: object
  - description: Join a user-scoped thread by ID
    name: join_user_thread
    params:
      example:
        after_cursor: string
        before_cursor: string
        include_metadata: true
        limit: 1
        thread_id: string
      properties:
        after_cursor:
          example: string
          type: string
        before_cursor:
          example: string
          type: string
        include_metadata:
          example: true
          type: boolean
        limit:
          example: 1
          type: integer
        thread_id:
          example: string
          type: string
      required:
      - thread_id
      type: object
    pattern: api:chat:user:thread:{thread_id}
    returns:
      type: object
  - description: Join a user-scoped transient (ephemeral) thread
    name: join_user_transient
    params:
      example:
        after_cursor: string
        before_cursor: string
        include_metadata: true
        key: string
        limit: 1
      properties:
        after_cursor:
          example: string
          type: string
        before_cursor:
          example: string
          type: string
        include_metadata:
          example: true
          type: boolean
        key:
          example: string
          type: string
        limit:
          example: 1
          type: integer
      required:
      - key
      type: object
    pattern: api:chat:user:transient:{key}
    returns:
      type: object
  - description: Join or create a team-scoped keyed thread
    name: join_team_keyed
    params:
      example:
        after_cursor: string
        before_cursor: string
        include_metadata: true
        key: string
        limit: 1
        team_id: string
      properties:
        after_cursor:
          example: string
          type: string
        before_cursor:
          example: string
          type: string
        include_metadata:
          example: true
          type: boolean
        key:
          example: string
          type: string
        limit:
          example: 1
          type: integer
        team_id:
          example: string
          type: string
      required:
      - key
      - team_id
      type: object
    pattern: api:chat:team:{team_id}:key:{key}
    returns:
      type: object
  - description: Join or create a user-scoped keyed thread
    name: join_user_keyed
    params:
      example:
        after_cursor: string
        before_cursor: string
        include_metadata: true
        key: string
        limit: 1
      properties:
        after_cursor:
          example: string
          type: string
        before_cursor:
          example: string
          type: string
        include_metadata:
          example: true
          type: boolean
        key:
          example: string
          type: string
        limit:
          example: 1
          type: integer
      required:
      - key
      type: object
    pattern: api:chat:user:key:{key}
    returns:
      type: object
  messages:
  - description: Add an emoji reaction to a message
    event: api:chat:add_reaction
    params:
      example:
        emoji: string
        message_id: string
      properties:
        emoji:
          example: string
          type: string
        message_id:
          example: string
          type: string
      required:
      - emoji
      - message_id
      type: object
    returns:
      description: 'Empty acknowledgement payload returned by channel message handlers that produce no data. The wire envelope is `{"status": "ok", "response": {}}`.'
      properties: {}
      type: object
  - description: Delete a message
    event: api:chat:delete_message
    params:
      example:
        message_id: string
      properties:
        message_id:
          example: string
          type: string
      required:
      - message_id
      type: object
    returns:
      description: 'Empty acknowledgement payload returned by channel message handlers that produce no data. The wire envelope is `{"status": "ok", "response": {}}`.'
      properties: {}
      type: object
  - description: Edit an existing message's content
    event: api:chat:edit_message
    params:
      example:
        content: string
        message_id: string
      properties:
        content:
          example: string
          type: string
        message_id:
          example: string
          type: string
      required:
      - content
      - message_id
      type: object
    returns:
      description: 'Empty acknowledgement payload returned by channel message handlers that produce no data. The wire envelope is `{"status": "ok", "response": {}}`.'
      properties: {}
      type: object


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