Scale AI Agent APIKeys API

openapi: 3.2.0
info:
  title: Agentex Agent APIKeys API
  version: 0.1.0
tags:
- name: Agent APIKeys
paths:
  /agent_api_keys:
    post:
      tags:
      - Agent APIKeys
      summary: Create Api Key
      operationId: create_api_key_agent_api_keys_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAPIKeyRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAPIKeyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Agent APIKeys
      summary: List API keys for an agent ID
      description: List API keys for an agent ID.
      operationId: list_agent_api_keys_agent_api_keys_get
      parameters:
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
      - name: agent_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Name
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          default: 50
          title: Limit
      - name: page_number
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
          title: Page Number
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentAPIKey'
                title: Response List Agent Api Keys Agent Api Keys Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agent_api_keys/webhook-trigger:
    post:
      tags:
      - Agent APIKeys
      summary: Create Webhook Trigger
      description: 'Wire a webhook trigger in one call.


        Registers the source''s signature-verification key (github/slack) for the agent and

        returns the ready-to-paste forward webhook URL plus the signing secret (shown once).

        The webhook then flows through the existing /agents/forward ingress, which verifies

        the signature against this key. Bundles the existing key-create + URL composition so

        a UI (or a curl) can set up a trigger without two steps.'
      operationId: create_webhook_trigger_agent_api_keys_webhook_trigger_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookTriggerRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateWebhookTriggerResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agent_api_keys/name/{name}:
    get:
      tags:
      - Agent APIKeys
      summary: Return named API key for the agent ID
      description: Return named API key for the agent ID.
      operationId: get_agent_api_key_by_name_agent_api_keys_name__name__get
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          title: Name
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
      - name: agent_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Name
      - name: api_key_type
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/AgentAPIKeyType'
          default: external
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentAPIKey'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agent_api_keys/{id}:
    get:
      tags:
      - Agent APIKeys
      summary: Return the API key by ID
      description: Return API key by ID.
      operationId: get_agent_api_key_agent_api_keys__id__get
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentAPIKey'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Agent APIKeys
      summary: Delete API key by ID
      description: Delete API key by ID.
      operationId: delete_agent_api_key_agent_api_keys__id__delete
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: string
                title: Response Delete Agent Api Key Agent Api Keys  Id  Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agent_api_keys/name/{api_key_name}:
    delete:
      tags:
      - Agent APIKeys
      summary: Delete API key by name
      description: Delete API key by name.
      operationId: delete_agent_api_key_by_name_agent_api_keys_name__api_key_name__delete
      parameters:
      - name: api_key_name
        in: path
        required: true
        schema:
          type: string
          title: Api Key Name
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
      - name: agent_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Name
      - name: api_key_type
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/AgentAPIKeyType'
          default: external
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: string
                title: Response Delete Agent Api Key By Name Agent Api Keys Name  Api Key Name  Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CreateAPIKeyRequest:
      properties:
        agent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
          description: The UUID of the agent
        agent_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Name
          description: The name of the agent - if not provided, the agent_id must be set.
        name:
          type: string
          title: Name
          description: The name of the agent's API key.
        api_key_type:
          $ref: '#/components/schemas/AgentAPIKeyType'
          description: The type of the agent API key (external by default).
          default: external
        api_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key
          description: Optionally provide the API key value - if not set, one will be generated.
      type: object
      required:
      - name
      title: CreateAPIKeyRequest
    CreateWebhookTriggerResponse:
      properties:
        key_id:
          type: string
          title: Key Id
          description: The created agent API key id.
        agent_name:
          type: string
          title: Agent Name
          description: The agent the webhook drives.
        source:
          $ref: '#/components/schemas/AgentAPIKeyType'
          description: Webhook source (github or slack).
        name:
          type: string
          title: Name
          description: Signature-lookup key (repo full_name / api_app_id).
        secret:
          type: string
          title: Secret
          description: The signing secret — shown once; paste into the source's webhook config.
        webhook_path:
          type: string
          title: Webhook Path
          description: The forward path to POST webhooks to.
        webhook_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Webhook Url
          description: Full webhook URL to paste into the source (None if no base URL configured).
      type: object
      required:
      - key_id
      - agent_name
      - source
      - name
      - secret
      - webhook_path
      title: CreateWebhookTriggerResponse
    CreateAPIKeyResponse:
      properties:
        id:
          type: string
          title: Id
          description: The unique identifier of the agent API key.
        agent_id:
          type: string
          title: Agent Id
          description: The UUID of the agent
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the agent API key was created
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: The optional name of the agent API key.
        api_key_type:
          $ref: '#/components/schemas/AgentAPIKeyType'
          description: The type of the created agent API key (external).
        api_key:
          type: string
          title: Api Key
          description: The value of the newly created API key.
      type: object
      required:
      - id
      - agent_id
      - created_at
      - name
      - api_key_type
      - api_key
      title: CreateAPIKeyResponse
    CreateWebhookTriggerRequest:
      properties:
        agent_name:
          type: string
          title: Agent Name
          description: The agent the webhook drives.
        source:
          $ref: '#/components/schemas/AgentAPIKeyType'
          description: Webhook source whose signature is verified (github or slack).
          default: github
        name:
          type: string
          title: Name
          description: 'Signature-lookup key: the repo full_name (github) or api_app_id (slack) that the forward ingress matches the incoming webhook against.'
        forward_path:
          type: string
          title: Forward Path
          description: Subpath the agent's own route handles, e.g. 'github-pr/<config-id>'. Appended to /agents/forward/name/{agent_name}/ to form the webhook URL.
        secret:
          anyOf:
          - type: string
          - type: 'null'
          title: Secret
          description: Signing secret. For GitHub, omit to generate one, or provide an existing webhook secret. For Slack, this is required and must be the Slack app's Signing Secret.
        base_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Base Url
          description: Optional public agentex base URL for the returned webhook_url; defaults to the AGENTEX_PUBLIC_URL env var.
      type: object
      required:
      - agent_name
      - name
      - forward_path
      title: CreateWebhookTriggerRequest
      description: 'One-call setup for a webhook trigger: register the source''s signature key and

        get back the ready-to-paste forward webhook URL.'
    AgentAPIKey:
      properties:
        id:
          type: string
          title: Id
          description: The unique identifier of the agent API key.
        agent_id:
          type: string
          title: Agent Id
          description: The UUID of the agent
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the agent API key was created
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: The optional name of the agent API key.
        api_key_type:
          $ref: '#/components/schemas/AgentAPIKeyType'
          description: The type of the agent API key (either internal or external)
      type: object
      required:
      - id
      - agent_id
      - created_at
      - name
      - api_key_type
      title: AgentAPIKey
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    AgentAPIKeyType:
      type: string
      enum:
      - internal
      - external
      - github
      - slack
      title: AgentAPIKeyType