openapi: 3.2.0
info:
  title: Anthropic User Profiles?beta=true API
servers:
- url: https://api.anthropic.com
tags:
- name: User Profiles?beta=true
paths:
  /v1/user_profiles?beta=true:
    post:
      operationId: BetaCreateUserProfile
      summary: Create User Profile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BetaCreateUserProfileRequest'
      responses:
        '200':
          description: Successful response (OK)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaUserProfile'
        '400':
          description: Invalid argument - The client specified an invalid argument
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '401':
          description: Unauthenticated - The request does not have valid authentication credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '403':
          description: Permission denied - The caller does not have permission to execute the specified operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '404':
          description: Not found - Some requested entity was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '408':
          description: Deadline exceeded - The deadline expired before the operation could complete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '409':
          description: Aborted - The operation was aborted due to concurrency issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '412':
          description: Failed precondition - Operation was rejected because the system is not in required state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '413':
          description: Out of range - Operation was attempted past the valid range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '429':
          description: Resource exhausted - Some resource has been exhausted (rate limiting)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '431':
          description: Request header fields too large - Request metadata was too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '499':
          description: Cancelled - The operation was cancelled by the client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '500':
          description: Internal - Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '501':
          description: Unimplemented - The operation is not implemented or supported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '503':
          description: Unavailable - The service is currently unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '504':
          description: Deadline exceeded - Upstream service did not respond in time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
      x-anthropic-beta-required:
      - user-profiles-2026-03-24
      - user-profiles-2026-08-18
      parameters:
      - name: anthropic-version
        in: header
        required: false
        schema:
          type: string
      - name: anthropic-beta
        in: header
        required: false
        schema:
          type: string
          items:
            type: string
          x-stainless-override-schema:
            x-stainless-param: betas
            x-stainless-extend-default: true
            type: array
            description: Optional header to specify the beta version(s) you want to use.
            items:
              $ref: '#/components/schemas/AnthropicBeta'
      tags:
      - User Profiles?beta=true
    get:
      operationId: BetaListUserProfiles
      summary: List User Profiles
      parameters:
      - name: x-api-key
        in: header
        required: false
        schema:
          type: string
      - name: anthropic-version
        in: header
        required: false
        schema:
          type: string
      - name: anthropic-beta
        in: header
        required: false
        schema:
          type: string
          items:
            type: string
          x-stainless-override-schema:
            x-stainless-param: betas
            x-stainless-extend-default: true
            type: array
            description: Optional header to specify the beta version(s) you want to use.
            items:
              $ref: '#/components/schemas/AnthropicBeta'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          format: int32
        description: Query parameter for limit
      - name: page
        in: query
        required: false
        schema:
          type: string
        description: Query parameter for page
      - name: order
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/BetaUserProfileListOrder'
        description: Query parameter for order
      responses:
        '200':
          description: Successful response (OK)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaListUserProfilesResponse'
        '400':
          description: Invalid argument - The client specified an invalid argument
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '401':
          description: Unauthenticated - The request does not have valid authentication credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '403':
          description: Permission denied - The caller does not have permission to execute the specified operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '404':
          description: Not found - Some requested entity was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '408':
          description: Deadline exceeded - The deadline expired before the operation could complete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '409':
          description: Aborted - The operation was aborted due to concurrency issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '412':
          description: Failed precondition - Operation was rejected because the system is not in required state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '413':
          description: Out of range - Operation was attempted past the valid range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '429':
          description: Resource exhausted - Some resource has been exhausted (rate limiting)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '431':
          description: Request header fields too large - Request metadata was too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '499':
          description: Cancelled - The operation was cancelled by the client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '500':
          description: Internal - Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '501':
          description: Unimplemented - The operation is not implemented or supported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '503':
          description: Unavailable - The service is currently unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
        '504':
          description: Deadline exceeded - Upstream service did not respond in time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaErrorResponse'
      x-anthropic-beta-required:
      - user-profiles-2026-03-24
      - user-profiles-2026-08-18
      tags:
      - User Profiles?beta=true
components:
  schemas:
    BetaGatewayTimeoutError:
      properties:
        message:
          default: Request timeout
          title: Message
          type: string
        type:
          const: timeout_error
          default: timeout_error
          title: Type
          type: string
      required:
      - message
      - type
      title: GatewayTimeoutError
      type: object
    BetaTimestamp:
      description: A timestamp in RFC 3339 format
      type: string
      format: date-time
    BetaOverloadedError:
      properties:
        message:
          default: Overloaded
          title: Message
          type: string
        type:
          const: overloaded_error
          default: overloaded_error
          title: Type
          type: string
      required:
      - message
      - type
      title: OverloadedError
      type: object
    BetaBillingError:
      properties:
        message:
          default: Billing error
          title: Message
          type: string
        type:
          const: billing_error
          default: billing_error
          title: Type
          type: string
      required:
      - message
      - type
      title: BillingError
      type: object
    BetaUserProfile:
      type: object
      additionalProperties: false
      required:
      - id
      - type
      - trust_grants
      - created_at
      - metadata
      - updated_at
      properties:
        id:
          description: Unique identifier for this user profile, prefixed `uprof_`.
          type: string
          examples:
          - uprof_011CZkZCu8hGbp5mYRQgUmz9
        type:
          description: Object type. Always `user_profile`.
          type: string
          enum:
          - user_profile
          examples:
          - user_profile
        external_id:
          description: Platform's own identifier for this user. Not enforced unique.
          anyOf:
          - type: string
          - type: 'null'
          examples:
          - user_12345
        name:
          description: Real-world name of the entity this profile represents (company or individual). For a resold-to company (`access_type` `passthrough`, or `relationship` `resold` under the `user-profiles-2026-03-24` header) this is that company's name.
          anyOf:
          - type: string
          - type: 'null'
          examples:
          - Example User
        relationship:
          description: How the entity relates to the platform. `external` (default), `resold`, or `internal`. Present under the `user-profiles-2026-03-24` beta header.
          allOf:
          - $ref: '#/components/schemas/BetaUserProfileRelationship'
          x-anthropic-beta-required:
          - user-profiles-2026-03-24
          examples:
          - external
        access_type:
          description: 'How the platform uses the API for this entity: `application` (default) or `passthrough`. Present under the `user-profiles-2026-08-18` beta header.'
          allOf:
          - $ref: '#/components/schemas/BetaUserProfileAccessType'
          x-anthropic-beta-required:
          - user-profiles-2026-08-18
        trust_grants:
          description: Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/BetaUserProfileTrustGrant'
          examples:
          - cyber:
              status: active
        created_at:
          description: When this user profile was created, in RFC 3339 format.
          allOf:
          - $ref: '#/components/schemas/BetaTimestamp'
          examples:
          - '2026-03-15T10:00:00Z'
        metadata:
          description: Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.
          type: object
          additionalProperties:
            type: string
          examples:
          - {}
        updated_at:
          description: When this user profile was last modified, in RFC 3339 format. Trust-grant status changes also bump this timestamp.
          allOf:
          - $ref: '#/components/schemas/BetaTimestamp'
          examples:
          - '2026-03-15T10:00:00Z'
      example:
        id: uprof_011CZkZCu8hGbp5mYRQgUmz9
        type: user_profile
        external_id: user_12345
        name: Example User
        relationship: external
        trust_grants:
          cyber:
            status: active
        metadata: {}
        created_at: '2026-03-15T10:00:00Z'
        updated_at: '2026-03-15T10:00:00Z'
    BetaAuthenticationError:
      properties:
        message:
          default: Authentication error
          title: Message
          type: string
        type:
          const: authentication_error
          default: authentication_error
          title: Type
          type: string
      required:
      - message
      - type
      title: AuthenticationError
      type: object
    BetaNotFoundError:
      properties:
        message:
          default: Not found
          title: Message
          type: string
        type:
          const: not_found_error
          default: not_found_error
          title: Type
          type: string
      required:
      - message
      - type
      title: NotFoundError
      type: object
    BetaUserProfileAccessType:
      type: string
      description: 'How the platform uses the API on behalf of the entity this profile represents. `application`: the platform sells a product that uses the API behind the scenes, and the profile represents an individual end-user of that product. `passthrough`: the platform resells raw inference, and the profile identifies the resold-to company.'
      enum:
      - application
      - passthrough
    BetaListUserProfilesResponse:
      type: object
      additionalProperties: false
      required:
      - data
      - next_page
      properties:
        data:
          description: User profiles on this page.
          type: array
          items:
            $ref: '#/components/schemas/BetaUserProfile'
          examples:
          - - id: uprof_011CZkZCu8hGbp5mYRQgUmz9
              type: user_profile
              external_id: user_12345
              name: Example User
              relationship: external
              trust_grants:
                cyber:
                  status: active
              metadata: {}
              created_at: '2026-03-15T10:00:00Z'
              updated_at: '2026-03-15T10:00:00Z'
        next_page:
          description: Cursor for the next page, or `null` when there are no more results.
          anyOf:
          - type: string
          - type: 'null'
          examples:
          - page_MjAyNS0wNS0xNFQwMDowMDowMFo=
      example:
        data:
        - id: uprof_011CZkZCu8hGbp5mYRQgUmz9
          type: user_profile
          external_id: user_12345
          name: Example User
          relationship: external
          trust_grants:
            cyber:
              status: active
          metadata: {}
          created_at: '2026-03-15T10:00:00Z'
          updated_at: '2026-03-15T10:00:00Z'
        next_page: page_MjAyNS0wNS0xNFQwMDowMDowMFo=
    BetaInvalidRequestError:
      properties:
        message:
          default: Invalid request
          title: Message
          type: string
        type:
          const: invalid_request_error
          default: invalid_request_error
          title: Type
          type: string
      required:
      - message
      - type
      title: InvalidRequestError
      type: object
    BetaPermissionError:
      properties:
        message:
          default: Permission denied
          title: Message
          type: string
        type:
          const: permission_error
          default: permission_error
          title: Type
          type: string
      required:
      - message
      - type
      title: PermissionError
      type: object
    BetaCreateUserProfileRequest:
      type: object
      additionalProperties: false
      properties:
        external_id:
          description: Platform's own identifier for this user. Not enforced unique. Maximum 255 characters.
          anyOf:
          - type: string
            minLength: 1
            maxLength: 255
          - type: 'null'
          examples:
          - user_12345
        name:
          description: Optional for all profiles. Real-world name of the entity this profile represents (company or individual); for a resold-to company (`relationship` `resold` / `access_type` `passthrough`), that company's name where known. Maximum 255 characters.
          anyOf:
          - type: string
            minLength: 1
            maxLength: 255
          - type: 'null'
        relationship:
          description: 'How the entity relates to the platform. `external` (default): an individual end-user. `resold`: a company the platform resells Claude access to. `internal`: the platform''s own usage.'
          allOf:
          - $ref: '#/components/schemas/BetaUserProfileRelationship'
          x-anthropic-beta-required:
          - user-profiles-2026-03-24
        access_type:
          description: 'How the platform uses the API for this entity. `application` (default): the profile represents an individual end-user of the platform''s product. `passthrough`: the profile identifies a company the platform resells Claude access to.'
          allOf:
          - $ref: '#/components/schemas/BetaUserProfileAccessType'
          x-anthropic-beta-required:
          - user-profiles-2026-08-18
        metadata:
          description: Free-form key-value data to attach to this user profile. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters. Values must be non-empty strings.
          type: object
          additionalProperties:
            type: string
          examples:
          - {}
      example:
        external_id: user_12345
        metadata: {}
    BetaUserProfileListOrder:
      type: string
      description: ListOrder enum
      enum:
      - asc
      - desc
    BetaUserProfileRelationship:
      type: string
      description: 'How the entity behind a user profile relates to the platform that owns the API key. `external`: an individual end-user of the platform. `resold`: a company the platform resells Claude access to. `internal`: the platform''s own usage.'
      enum:
      - external
      - resold
      - internal
    BetaErrorResponse:
      properties:
        error:
          discriminator:
            mapping:
              api_error: '#/components/schemas/BetaAPIError'
              authentication_error: '#/components/schemas/BetaAuthenticationError'
              billing_error: '#/components/schemas/BetaBillingError'
              invalid_request_error: '#/components/schemas/BetaInvalidRequestError'
              not_found_error: '#/components/schemas/BetaNotFoundError'
              overloaded_error: '#/components/schemas/BetaOverloadedError'
              permission_error: '#/components/schemas/BetaPermissionError'
              rate_limit_error: '#/components/schemas/BetaRateLimitError'
              timeout_error: '#/components/schemas/BetaGatewayTimeoutError'
            propertyName: type
          oneOf:
          - $ref: '#/components/schemas/BetaInvalidRequestError'
          - $ref: '#/components/schemas/BetaAuthenticationError'
          - $ref: '#/components/schemas/BetaBillingError'
          - $ref: '#/components/schemas/BetaPermissionError'
          - $ref: '#/components/schemas/BetaNotFoundError'
          - $ref: '#/components/schemas/BetaRateLimitError'
          - $ref: '#/components/schemas/BetaGatewayTimeoutError'
          - $ref: '#/components/schemas/BetaAPIError'
          - $ref: '#/components/schemas/BetaOverloadedError'
          title: Error
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Request Id
        type:
          const: error
          default: error
          title: Type
          type: string
      required:
      - error
      - request_id
      - type
      title: ErrorResponse
      type: object
    BetaAPIError:
      properties:
        message:
          default: Internal server error
          title: Message
          type: string
        type:
          const: api_error
          default: api_error
          title: Type
          type: string
      required:
      - message
      - type
      title: APIError
      type: object
    AnthropicBeta:
      anyOf:
      - type: string
      - type: string
        enum:
        - message-batches-2024-09-24
        - prompt-caching-2024-07-31
        - computer-use-2024-10-22
        - computer-use-2025-01-24
        - pdfs-2024-09-25
        - token-counting-2024-11-01
        - token-efficient-tools-2025-02-19
        - output-128k-2025-02-19
        - files-api-2025-04-14
        - mcp-client-2025-04-04
        - mcp-client-2025-11-20
        - dev-full-thinking-2025-05-14
        - interleaved-thinking-2025-05-14
        - code-execution-2025-05-22
        - extended-cache-ttl-2025-04-11
        - context-1m-2025-08-07
        - context-management-2025-06-27
        - model-context-window-exceeded-2025-08-26
        - skills-2025-10-02
        - fast-mode-2026-02-01
        - output-300k-2026-03-24
        - user-profiles-2026-03-24
        - user-profiles-2026-08-18
        - advisor-tool-2026-03-01
        - managed-agents-2026-04-01
        - cache-diagnosis-2026-04-07
        - dreaming-2026-04-21
        - thinking-token-count-2026-05-13
        - server-side-fallback-2026-06-01
        - server-side-fallback-2026-07-01
        - fallback-credit-2026-06-01
        - fallback-credit-2026-07-01
        - agent-memory-2026-07-22
        - mid-conversation-tool-changes-2026-07-01
        - compact-2026-01-12
        - computer-use-2025-11-24
        - mcp-tunnels-2026-06-22
        - structured-outputs-2025-11-13
        - task-budgets-2026-03-13
        - thinking-display-updates-2026-08-18
        - ce-user-management-2026-07-13
        x-stainless-nominal: false
    BetaRateLimitError:
      properties:
        message:
          default: Rate limited
          title: Message
          type: string
        type:
          const: rate_limit_error
          default: rate_limit_error
          title: Type
          type: string
      required:
      - message
      - type
      title: RateLimitError
      type: object
    BetaUserProfileTrustGrant:
      type: object
      additionalProperties: false
      required:
      - status
      properties:
        status:
          description: Status of the trust grant.
          type: string
          enum:
          - active
          - pending
          - rejected
          examples:
          - active
      example:
        status: active