> ## Documentation Index
> Fetch the complete documentation index at: https://docs.matrices.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an agent



## OpenAPI

````yaml /openapi/platform.v1.json post /v1/agents
openapi: 3.0.3
info:
  description: Public platform API for catalog and proxied data-plane routes.
  title: Matrices Platform API
  version: v1
servers:
  - url: https://api.matrices.com
security: []
tags:
  - description: Authenticated bearer credential context.
    name: auth
    x-group: Auth
  - description: Write-only provider credentials with safe connection metadata.
    name: connections
    x-group: Connections
  - description: Materialized workspace principals and active agent counts.
    name: identities
    x-group: Identities
  - description: Remote MCP server registrations.
    name: toolsets
    x-group: Toolsets
  - description: Named allow-only agent tool permissions.
    name: roles
    x-group: Roles
  - description: Client-executed tool calls.
    name: tools
    x-group: Tools
  - description: Reusable agent behavior profiles.
    name: profiles
    x-group: Profiles
  - description: Workspace-owned agent identities.
    name: agents
    x-group: Agents
  - description: Immutable private image inputs.
    name: images
    x-group: Images
  - description: Public model catalog.
    name: models
    x-group: Models
  - description: Running agent threads.
    name: threads
    x-group: Threads
  - description: Agent schedules.
    name: schedules
    x-group: Schedules
  - description: Workspace append-only feeds.
    name: feeds
    x-group: Feeds
  - description: Agent subscriptions over workspace feeds.
    name: subscriptions
    x-group: Subscriptions
  - description: Agent-private and workspace-shared durable memory notes.
    name: memory
    x-group: Memory
  - description: Thread messages.
    name: messages
    x-group: Messages
  - description: Thread event log data.
    name: events
    x-group: Events
  - description: Runtime hook audit and wait resolution.
    name: hooks
    x-group: Hooks
paths:
  /v1/agents:
    post:
      tags:
        - agents
      summary: Create an agent
      operationId: CreateAgent
      requestBody:
        content:
          application/json:
            examples:
              inline:
                summary: Create an agent with a fresh behavior profile
                value:
                  identity: svc:researcher
                  name: Researcher
                  profile:
                    models:
                      - openai/gpt-5.4
                    systemPrompt: Research the user's question carefully.
              profile:
                summary: Create an agent from an existing profile
                value:
                  identity: svc:researcher
                  profileId: profile_123
            schema:
              anyOf:
                - $ref: '#/components/schemas/AgentCreateRequest'
                - $ref: '#/components/schemas/AgentLeaseCreateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
          description: Created agent.
        '202':
          $ref: '#/components/responses/PendingOperation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/CatalogUnavailable'
      security:
        - APIKeyBearer: []
        - AgentLeaseBearer: []
components:
  schemas:
    AgentCreateRequest:
      additionalProperties: false
      oneOf:
        - not:
            required:
              - profile
          required:
            - profileId
        - not:
            required:
              - profileId
          required:
            - profile
            - name
      properties:
        avatar:
          description: >-
            Slack emoji shortcode such as :fox_face:, or an https image URL.
            Agent-authored writes accept only the emoji form. Empty clears.
          maxLength: 2048
          pattern: ^(?:|:[a-z0-9_+'-]{1,64}:|https://\S+)$
          type: string
        budget:
          $ref: '#/components/schemas/Budget'
        description:
          type: string
        identity:
          $ref: '#/components/schemas/Identity'
        name:
          type: string
        profile:
          $ref: '#/components/schemas/AgentCreateProfile'
        profileId:
          minLength: 1
          pattern: \S
          type: string
        tags:
          items:
            type: string
          maxItems: 32
          type: array
      required:
        - identity
      type: object
    AgentLeaseCreateRequest:
      additionalProperties: false
      description: Identity-less create body accepted from AgentLeaseBearer callers.
      oneOf:
        - not:
            required:
              - profile
          required:
            - profileId
        - not:
            required:
              - profileId
          required:
            - profile
            - name
      properties:
        avatar:
          description: >-
            Slack emoji shortcode such as :fox_face:, or an https image URL.
            Agent-authored writes accept only the emoji form. Empty clears.
          maxLength: 2048
          pattern: ^(?:|:[a-z0-9_+'-]{1,64}:|https://\S+)$
          type: string
        budget:
          $ref: '#/components/schemas/Budget'
        description:
          type: string
        name:
          type: string
        profile:
          $ref: '#/components/schemas/AgentCreateProfile'
        profileId:
          minLength: 1
          pattern: \S
          type: string
        tags:
          items:
            type: string
          maxItems: 32
          type: array
      type: object
    AgentResponse:
      properties:
        agent:
          $ref: '#/components/schemas/Agent'
      required:
        - agent
      type: object
    Budget:
      additionalProperties: false
      properties:
        limit:
          format: double
          minimum: 0
          type: number
        window:
          enum:
            - 24h
            - 7d
            - total
          type: string
      required:
        - limit
        - window
      type: object
    Identity:
      description: >-
        Provenance identity. Surrounding whitespace is trimmed on input; values
        may contain at most 512 UTF-8 bytes and no Unicode control characters.
      type: string
    AgentCreateProfile:
      additionalProperties: false
      properties:
        hooks:
          description: >-
            Omit to use the default approval hooks. Use an empty array for no
            hooks.
          items:
            $ref: '#/components/schemas/HookDefinition'
          maxItems: 16
          type: array
        models:
          description: >-
            Ordered model selectors. Each selector contributes one preferred
            concrete target while authorizing all current matches.
          items:
            $ref: '#/components/schemas/ModelSelector'
          maxItems: 8
          minItems: 1
          type: array
        roleIds:
          description: >-
            Role grants for the fresh profile. When an agent creates an agent,
            omitting this field inherits the caller's turn-start role ids and an
            empty array creates a tool-less profile; for other callers, omitting
            it creates a profile with no role access.
          items:
            type: string
          maxItems: 8
          type: array
        systemPrompt:
          maxLength: 4096
          minLength: 1
          type: string
      required:
        - models
        - systemPrompt
      type: object
    Agent:
      properties:
        avatar:
          description: >-
            Slack emoji shortcode such as :fox_face:, or an https image URL.
            Agent-authored writes accept only the emoji form. Empty clears.
          maxLength: 2048
          pattern: ^(?:|:[a-z0-9_+'-]{1,64}:|https://\S+)$
          type: string
        budget:
          $ref: '#/components/schemas/Budget'
        createdAt:
          format: date-time
          type: string
        description:
          type: string
        id:
          type: string
        identity:
          $ref: '#/components/schemas/Identity'
        name:
          type: string
        profileId:
          type: string
        tags:
          items:
            type: string
          maxItems: 32
          type: array
        workspaceId:
          type: string
      required:
        - id
        - workspaceId
        - profileId
        - tags
        - createdAt
      type: object
    OperationResponse:
      additionalProperties: false
      properties:
        operation:
          $ref: '#/components/schemas/Operation'
      required:
        - operation
      type: object
    ErrorResponse:
      properties:
        attemptsRemaining:
          type: integer
        code:
          type: string
        error:
          type: string
        message:
          type: string
        retryAfterSeconds:
          type: integer
      required:
        - error
        - message
      type: object
    HookDefinition:
      properties:
        asyncTimeoutMs:
          format: int64
          type: integer
        id:
          description: Slug-shaped hook id, unique within the profile.
          type: string
        match:
          $ref: '#/components/schemas/HookMatch'
        onFailure:
          $ref: '#/components/schemas/HookFailurePolicy'
        point:
          $ref: '#/components/schemas/HookPoint'
        processor:
          $ref: '#/components/schemas/HookProcessor'
        timeoutMs:
          format: int64
          type: integer
      required:
        - id
        - point
        - processor
      type: object
    ModelSelector:
      description: >-
        An exact catalog id, `*`, or a provider/family prefix ending in `*` (for
        example `anthropic/*`). Wildcards are dynamic authorization; future
        matching catalog targets become selectable without a profile edit, and
        platform precedence chooses each selector's preferred target.
      example: anthropic/claude-sonnet*
      maxLength: 512
      minLength: 1
      pattern: ^(?:\*|[^*\s]+|[^*\s]*/[^*\s]*\*)$
      type: string
    Operation:
      additionalProperties: false
      properties:
        action:
          type: string
        agentId:
          type: string
        createdAt:
          format: date-time
          type: string
        expiresAt:
          format: date-time
          type: string
        id:
          type: string
        resolvedAt:
          format: date-time
          type: string
        resolvedBy:
          $ref: '#/components/schemas/Principal'
        result:
          $ref: '#/components/schemas/OperationResult'
        state:
          $ref: '#/components/schemas/OperationState'
      required:
        - id
        - agentId
        - action
        - state
        - createdAt
        - expiresAt
      type: object
    HookMatch:
      properties:
        tools:
          items:
            type: string
          type: array
        where:
          items:
            $ref: '#/components/schemas/MatchCondition'
          type: array
      type: object
    HookFailurePolicy:
      enum:
        - fail_closed
        - fail_open
      type: string
    HookPoint:
      enum:
        - before_turn_start
        - before_tool_call
        - after_tool_result
        - after_model_response
      type: string
    HookProcessor:
      properties:
        agentId:
          type: string
        type:
          $ref: '#/components/schemas/HookProcessorType'
        url:
          type: string
      required:
        - type
      type: object
    Principal:
      properties:
        id:
          type: string
        identity:
          $ref: '#/components/schemas/Identity'
        origin:
          $ref: '#/components/schemas/Origin'
        type:
          enum:
            - user
            - api_key
            - agent
            - schedule
            - trigger
            - subscription
          type: string
      required:
        - type
        - id
      type: object
    OperationResult:
      additionalProperties: false
      properties:
        body: {}
        status:
          maximum: 599
          minimum: 100
          type: integer
      required:
        - status
      type: object
    OperationState:
      enum:
        - pending
        - denied
        - expired
        - executing
        - executed
        - failed
      type: string
    MatchCondition:
      properties:
        op:
          $ref: '#/components/schemas/MatchOp'
        path:
          type: string
        quantifier:
          $ref: '#/components/schemas/MatchQuantifier'
        value:
          $ref: '#/components/schemas/JSONValue'
      required:
        - path
        - op
      type: object
    HookProcessorType:
      enum:
        - url
        - agent
        - client
      type: string
    Origin:
      additionalProperties: false
      description: >-
        Caller-asserted external event metadata. Only trigger principals may
        assert it; every other principal is rejected.
      properties:
        channelId:
          description: Provider channel identifier, limited to 512 UTF-8 bytes.
          type: string
        messageId:
          description: Provider message identifier, limited to 512 UTF-8 bytes.
          type: string
        provider:
          $ref: '#/components/schemas/OriginProvider'
        senderId:
          description: Provider sender identifier, limited to 512 UTF-8 bytes.
          type: string
        tenantId:
          description: Provider tenant identifier, limited to 512 UTF-8 bytes.
          type: string
        threadId:
          description: Provider thread identifier, limited to 512 UTF-8 bytes.
          type: string
      required:
        - provider
        - tenantId
        - senderId
      type: object
    MatchOp:
      enum:
        - eq
        - neq
        - prefix
        - not_prefix
        - suffix
        - not_suffix
        - contains
        - not_contains
        - in
        - not_in
        - exists
        - absent
      type: string
    MatchQuantifier:
      enum:
        - any
        - all
      type: string
    JSONValue:
      description: Arbitrary JSON value.
    OriginProvider:
      description: >-
        Caller-asserted external event provider. This value carries no
        authority.
      enum:
        - slack
      type: string
  responses:
    PendingOperation:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OperationResponse'
      description: >-
        Request parked for workspace approval. Poll the returned operation
        handle for a terminal result.
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Invalid request.
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Resource not found.
    CatalogUnavailable:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Platform catalog database is not configured or unavailable.
  securitySchemes:
    APIKeyBearer:
      scheme: bearer
      type: http
    AgentLeaseBearer:
      description: >-
        Short-lived agent lease bearer installed in a sandbox provider HTTP
        boundary. Requests run as the owning agent and are checked against live
        agent permissions.
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.