Archastro Users 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 Users API
  version: v1
tags:
- name: Users
paths:
  /api/v1/users/me:
    get:
      description: 'Returns the user associated with the authenticated session or bearer

        token. This is the canonical way to resolve "who am I?" after

        authentication.


        The response includes the user''s profile, notification settings, and

        profile picture, along with the app, organization, and sandbox the

        token is scoped to and their display names — enough to establish full

        session context in a single call. Unauthenticated requests return 401.'
      operationId: get_api_v1_users_me
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: Successful response
        '401':
          description: Unauthorized
      summary: Retrieve the current user
      x-auth:
      - bearer
      - publishable_key
      tags:
      - Users
  /api/v1/users/{user}:
    get:
      description: 'Returns the user identified by `user`. The authenticated user must share

        at least one team with the target user; requests for users outside any

        shared team are rejected with 403.


        A user may always retrieve their own profile with this endpoint. Use the

        `GET /users/me` endpoint as a convenience alias for retrieving the

        authenticated user without specifying an ID.'
      operationId: get_api_v1_users__user
      parameters:
      - description: User ID (`usr_...`) of the user to retrieve.
        example: string
        in: path
        name: user
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: Successful response
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      summary: Retrieve a user by ID
      x-auth:
      - bearer
      - publishable_key
      tags:
      - Users
  /api/v1/users/{user}/artifacts:
    get:
      description: 'Returns all artifacts owned by the specified user. Artifacts represent

        AI-generated or user-uploaded files associated with agent sessions,

        threads, or sandboxes — such as images, documents, and code outputs.


        The authenticated user must be requesting their own artifacts or must

        have administrative access. Attempting to list artifacts for a user

        the caller is not authorized to access returns 403.


        Results are returned in a single page without cursor pagination. Each

        artifact in the response reflects the state of its current version,

        including a short-lived signed `file_url` for direct download.'
      operationId: get_api_v1_users__user_artifacts
      parameters:
      - description: User ID (`usr_...`). The authenticated user must be this user or have access to their artifacts.
        example: string
        in: path
        name: user
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                description: All artifacts owned by the user.
                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 belonging to the user.
                    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
      summary: List a user's artifacts
      x-auth:
      - bearer
      - publishable_key
      tags:
      - Users
    post:
      description: 'Creates a new artifact and stores its file content. A file payload is required;

        supply it via the `artifact.file_content` (Base64-encoded), `artifact.file_name`,

        and `artifact.file_content_type` fields. The artifact is scoped to the owner

        resolved from the request context — either a team or a user.


        Optionally associate the artifact with an existing thread or agent by passing

        `artifact.thread_id` or `artifact.agent_id`. Returns 201 with the created

        artifact on success.'
      operationId: post_api_v1_users__user_artifacts
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              example:
                artifact: {}
              properties:
                artifact:
                  description: Object containing the attributes for the new artifact.
                  example: {}
                  type: object
              required:
              - artifact
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Artifact'
          description: Successful response
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Validation error
      summary: Create an artifact
      x-auth:
      - bearer
      - publishable_key
      tags:
      - Users
  /api/v1/users/{user}/invites:
    post:
      description: 'Creates a new invite for the authenticated user. The invite can optionally be

        scoped to a specific thread, a persona, or carry arbitrary metadata. The

        caller receives the new invite object at HTTP 201.


        The invite key is always generated server-side (192-bit URL-safe random

        string) and cannot be supplied by the caller.


        The path `:user` must match the authenticated user. If a `thread_id` is

        provided, the authenticated user must have permission to invite others to that

        thread; team threads are not supported and return an error. Supplying a

        `thread_id` that does not exist or that belongs to a different user returns

        an error. If a key collision occurs during creation the call returns a 409

        conflict — simply retry to generate a new key.'
      operationId: post_api_v1_users__user_invites
      parameters:
      - description: User ID (`usr_...`). Must match the authenticated user.
        example: string
        in: path
        name: user
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              example:
                invite:
                  metadata:
                    key: value
                  persona_id: string
                  thread_id: string
              properties:
                invite:
                  description: Parameters for the new invite. See the UserInviteCreateParams schema for field details.
                  example:
                    metadata:
                      key: value
                    persona_id: string
                    thread_id: string
                  properties:
                    metadata:
                      description: Arbitrary key-value metadata to attach to the invite. Returned as-is on the resulting invite object.
                      example:
                        key: value
                      type: object
                    persona_id:
                      description: ID of the persona to associate with this invite (`per_...`). `null` if the invite is not bound to a persona.
                      example: string
                      type: string
                    thread_id:
                      description: ID of the thread to associate with this invite (`thr_...`). `null` if the invite is not bound to a thread.
                      example: string
                      type: string
                  type: object
              required:
              - invite
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInvite'
          description: Successful response
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Thread not found
        '409':
          description: Resource already exists
        '422':
          description: Validation failed; Invites cannot be created for team threads; Invalid thread id; User context is required
      summary: Create a user invite
      x-auth:
      - bearer
      - publishable_key
      tags:
      - Users
  /api/v1/users/{user}/orgs:
    get:
      description: 'Returns the organizations the specified user belongs to. A user can belong

        to at most one organization, so the `data` array contains either zero or one

        items.


        The authenticated viewer must have permission to inspect the target user.

        Returns an empty `data` array when the user has no organization membership.'
      operationId: get_api_v1_users__user_orgs
      parameters:
      - description: User ID (`usr_...`) whose organization membership you want to retrieve.
        example: string
        in: path
        name: user
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                description: The user's organization memberships.
                example:
                  data:
                  - created_at: '2024-01-01T00:00:00Z'
                    description: An example description.
                    domain: acme.com
                    id: org_0aBcDeFgHiJkLmNoPqRsTu
                    industry: fintech
                    name: Example Name
                    onboarding_track: vendor
                    sandbox: dsb_0aBcDeFgHiJkLmNoPqRsTu
                    slug: example-slug
                    status: active
                    updated_at: '2024-01-01T00:00:00Z'
                    website: https://example.com
                properties:
                  data:
                    description: Array of organization objects the user belongs to. Contains at most one item.
                    example:
                    - created_at: '2024-01-01T00:00:00Z'
                      description: An example description.
                      domain: acme.com
                      id: org_0aBcDeFgHiJkLmNoPqRsTu
                      industry: fintech
                      name: Example Name
                      onboarding_track: vendor
                      sandbox: dsb_0aBcDeFgHiJkLmNoPqRsTu
                      slug: example-slug
                      status: active
                      updated_at: '2024-01-01T00:00:00Z'
                      website: https://example.com
                    items:
                      description: A full organization object returned on org management endpoints. Includes identity, branding, and onboarding metadata for the authenticated caller's organization.
                      example:
                        created_at: '2024-01-01T00:00:00Z'
                        description: An example description.
                        domain: acme.com
                        id: org_0aBcDeFgHiJkLmNoPqRsTu
                        industry: fintech
                        name: Example Name
                        onboarding_track: vendor
                        sandbox: dsb_0aBcDeFgHiJkLmNoPqRsTu
                        slug: example-slug
                        status: active
                        updated_at: '2024-01-01T00:00:00Z'
                        website: https://example.com
                      properties:
                        created_at:
                          description: When this organization was created (ISO 8601).
                          example: '2024-01-01T00:00:00Z'
                          format: date-time
                          type: string
                        description:
                          description: Short human-readable description of the organization. `null` if not set.
                          example: An example description.
                          type: string
                        domain:
                          description: Primary domain associated with the organization, e.g. `"acme.com"`. `null` if not configured.
                          example: acme.com
                          type: string
                        id:
                          description: Organization ID (`org_...`).
                          example: org_0aBcDeFgHiJkLmNoPqRsTu
                          type: string
                        industry:
                          description: Industry category the organization belongs to, e.g. `"fintech"` or `"healthcare"`. `null` if not set.
                          example: fintech
                          type: string
                        name:
                          description: Display name of the organization. `null` if the org has not set a name.
                          example: Example Name
                          type: string
                        onboarding_track:
                          description: The new-user experience track this org first completed. `"vendor"` for orgs that onboarded as service providers; `"customer"` for orgs that onboarded as buyers. `null` if onboarding was not tracked.
                          example: vendor
                          type: string
                        sandbox:
                          description: ID of the sandbox environment scoped to this organization (`snd_...`). `null` for organizations in production mode.
                          example: dsb_0aBcDeFgHiJkLmNoPqRsTu
                          type: string
                        slug:
                          description: URL-safe identifier for the organization, used in vanity URLs and slug-based lookups.
                          example: example-slug
                          type: string
                        status:
                          description: Current lifecycle status of the organization, e.g. `"active"` or `"suspended"`. `null` if the status has not been set.
                          example: active
                          type: string
                        updated_at:
                          description: When this organization was last modified (ISO 8601).
                          example: '2024-01-01T00:00:00Z'
                          format: date-time
                          type: string
                        website:
                          description: Public website URL for the organization. `null` if not set.
                          example: https://example.com
                          type: string
                      required:
                      - id
                      type: object
                    type: array
                required:
                - data
                type: object
          description: Successful response
        '401':
          description: Unauthorized
      summary: List organizations for a user
      x-auth:
      - bearer
      - publishable_key
      tags:
      - Users
  /api/v1/users/{user}/profile:
    put:
      description: 'Updates one or more profile fields for the authenticated user. All

        fields are optional; omit any you do not want to change.


        When `profile_picture` is supplied, the image is uploaded and replaces

        the existing picture. The previous picture is deleted after the new one

        is stored. Image upload failures return 422 without modifying other

        profile fields.'
      operationId: put_api_v1_users__user_profile
      parameters:
      - description: User ID (`usr_...`) or `"me"` for the authenticated user.
        example: string
        in: path
        name: user
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              example:
                alias: string
                full_name: Example Name
                metadata:
                  key: value
                profile_picture:
                  data: string
                  filename: string
                  mime_type: application/json
              properties:
                alias:
                  description: Short display alias shown in place of the full name in compact UI contexts.
                  example: string
                  type: string
                full_name:
                  description: Updated display name for the user.
                  example: Example Name
                  type: string
                metadata:
                  description: Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass `null` for a key to remove it.
                  example:
                    key: value
                  type: object
                profile_picture:
                  description: New profile picture to upload as a base64-encoded image. Replaces any existing picture.
                  example:
                    data: string
                    filename: string
                    mime_type: application/json
                  properties:
                    data:
                      description: Base64-encoded binary content of the image file.
                      example: string
                      type: string
                    filename:
                      description: Original filename of the image, used for storage metadata.
                      example: string
                      type: string
                    mime_type:
                      description: MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`.
                      example: application/json
                      type: string
                  type: object
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: Successful response
        '401':
          description: Unauthorized
        '422':
          description: Validation error
      summary: Update the current user's profile
      x-auth:
      - bearer
      - publishable_key
      tags:
      - Users
  /api/v1/users/{user}/threads:
    get:
      description: 'Returns all threads visible to the specified user. The authenticated caller must

        have access to the target user''s account; a 403 is returned otherwise.


        Pass one or more `agent` IDs to narrow results to threads where at least one of

        the listed agents is also a member — useful for displaying every thread a user

        shares with a particular agent. Pass one or more `filter` objects to narrow

        results by thread metadata key/value pairs. Both narrowings may be combined in

        a single request.


        Results are returned as a flat array; no cursor-based pagination is applied.'
      operationId: get_api_v1_users__user_threads
      parameters:
      - description: Array of agent user IDs (`usr_...`). When provided, only threads where at least one of the listed agents is also a member are returned. Omit or pass an empty array to return all threads regardless of agent membership.
        example:
        - string
        in: query
        name: agent
        required: false
        schema:
          items:
            type: string
          type: array
      - description: Array of metadata filter objects. Each filter matches threads whose `metadata` map contains the specified key/value pair. All filters must match (logical AND). Omit to return threads regardless of metadata.
        example:
        - key: string
          type: metadata
          value: string
        in: query
        name: filter
        required: false
        schema:
          items:
            description: A simple key-value predicate for matching a top-level metadata field. Use MetadataQuery for compound boolean expressions.
            example:
              key: string
              type: metadata
              value: string
            properties:
              key:
                description: Top-level key of the metadata object to match against.
                example: string
                type: string
              type:
                description: Filter discriminator. Must be `"metadata"` to identify this as a metadata filter.
                example: metadata
                type: string
              value:
                description: Expected value for the given `key`. Matched with strict equality against the stored metadata.
                example: string
                type: string
            required:
            - key
            - type
            - value
            type: object
          type: array
      - description: User ID (`usr_...`) whose threads should be listed.
        example: string
        in: path
        name: user
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Listing of threads visible t

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