Scale AI Agent Configs API

openapi: 3.2.0
info:
  title: EGP API V5 Agent Configs API
  description: This is the parent API for all EGP APIs. If you are looking for the EGP API, please go to https://api.egp.scale.com/docs.
  contact:
    name: Scale Generative AI Platform
    url: https://scale.com/genai-platform
  version: 0.1.0
servers:
- url: https://api.egp.scale.com
security: []
tags:
- name: Agent Configs
paths:
  /v5/agent_configs:
    post:
      tags:
      - Agent Configs
      summary: Create Agent Config
      description: 'Create a reusable agent configuration (system prompt, harness, model, allowed tools) under the caller''s account.


        The config is a template that a chat session or a non-chat trigger later turns

        into task params; creating one does not start any task. ``persistent_workspace``

        opts tasks made from this config into a durable ``/workspace`` that survives

        sandbox death (off by default, and fixed once a task starts), and ``repos``

        overrides which repositories provisioning clones into that workspace — omit it

        (null) to use the deployment default, or pass an empty list to clone nothing.

        A ``repos`` override is rejected with a 422 on the model-agnostic (litellm)

        harness unless ``persistent_workspace`` is also true, because non-persistent

        litellm tasks run in a pre-cloned warm-pool sandbox where the override would be

        ignored. ``allowed_tools`` may name MCP servers (Slack, Linear, GitHub, ...)

        alongside harness tools, and granting an MCP server name authorizes every tool

        it exposes.'
      operationId: POST-V5-/v5/agent_configs
      parameters:
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentConfigRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConfig'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/agent-configs/create-agent-config
    get:
      tags:
      - Agent Configs
      summary: List Agent Configs
      description: 'List agent configurations visible to the caller, with cursor-based pagination.


        A user caller sees only the configs they created unless fine-grained access

        control (FGAC) grants them access to others; a service-account caller sees

        every config under the account. This returns the stored config records as-is —

        use ``{agent_config_id}/resolve`` instead when you need a config projected into

        the params a task would run with. Because deleting a config removes it outright

        rather than archiving it, there are no archived configs to page through here.'
      operationId: GET-V5-/v5/agent_configs
      parameters:
      - name: starting_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Starting After
      - name: ending_before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Ending Before
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 10000
          minimum: 1
          default: 100
          title: Limit
      - name: sort_by
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Sort By
      - name: sort_order
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/SortOrder'
          - type: 'null'
          default: asc
          title: Sort Order
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList_AgentConfig_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/agent-configs/list-agent-configs
  /v5/agent_configs/{agent_config_id}:
    delete:
      tags:
      - Agent Configs
      summary: Delete Agent Config (hard delete)
      description: 'Permanently delete an agent config; this is a hard delete, not an archive, so the row is removed and cannot be restored.


        Because a config is only a template, deleting it does not stop or alter any task

        already created from it. A user caller can only delete a config they created

        unless fine-grained access control grants access. The response echoes the

        deleted id.'
      operationId: DELETE-V5-/v5/agent_configs/agent_config_id
      parameters:
      - name: agent_config_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Config Id
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse_AgentConfig_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/agent-configs/delete-agent-config-hard-delete
    get:
      tags:
      - Agent Configs
      summary: Get Agent Config
      description: 'Fetch a single stored agent configuration by id, including its ``persistent_workspace`` flag and any ``repos`` override.


        This returns the saved record as-is and does not compute task params; use

        ``{agent_config_id}/resolve`` when you need the config projected into the params

        a task would run with. A user caller can only read a config they created unless

        fine-grained access control grants access, while a service account can read any

        config under the account; a missing or out-of-scope id returns a 404.'
      operationId: GET-V5-/v5/agent_configs/agent_config_id
      parameters:
      - name: agent_config_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Config Id
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConfig'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/agent-configs/get-agent-config
    patch:
      tags:
      - Agent Configs
      summary: Update Agent Config
      description: 'Partially update a stored agent config; only fields present in the request body are changed.


        ``persistent_workspace`` and ``repos`` are both patchable — an explicit null on

        ``repos`` clears the override back to the deployment default, while the

        always-present fields (name, system_prompt, harness, allowed_tools, model, and

        persistent_workspace) reject an explicit null. Because ``persistent_workspace``

        and ``repos`` are read when a task is created and are fixed for a task''s life,

        changing them affects only tasks created afterward, not one already running. The

        optional ``task_id`` query parameter opts into a live-config side effect: after

        the row is persisted, the changed pass-through fields (system_prompt, model,

        harness, and allowed_tools split into harness tools versus MCP servers) are

        shallow-merged into that running task''s params on Agentex in a background task so

        the worker picks them up on its next turn; ``persistent_workspace`` and ``repos``

        are intentionally not forwarded to a running task. That side effect runs after

        the response is sent, is best-effort, and no-ops if the task does not exist or the

        caller does not own it. A user caller can only update a config they created unless

        fine-grained access control grants access.'
      operationId: PATCH-V5-/v5/agent_configs/agent_config_id
      parameters:
      - name: agent_config_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Config Id
      - name: task_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: If set, after persisting the patch we shallow-merge the changed fields into this task's params column on Agentex so the worker picks up the new values on its next turn. Caller-provided context — Agentex enforces task ownership via its own auth, so the side-effect no-ops if the caller doesn't own the task.
          title: Task Id
        description: If set, after persisting the patch we shallow-merge the changed fields into this task's params column on Agentex so the worker picks up the new values on its next turn. Caller-provided context — Agentex enforces task ownership via its own auth, so the side-effect no-ops if the caller doesn't own the task.
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentConfigRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConfig'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/agent-configs/update-agent-config
  /v5/agent_configs/mcp_tools:
    get:
      tags:
      - Agent Configs
      summary: List MCP Tool Names
      description: 'Return the fixed set of tool names that route to MCP servers rather than harness-provided tools.


        These are the subset of ``allowed_tools`` values (Slack, Linear, GitHub, ...)

        the platform treats as MCP servers; the list is a static enum, not account

        data, so it is identical for every caller. It is exposed mainly so the

        generated SDK carries the ``McpTool`` type and the frontend can assert its own

        MCP-versus-harness tool classifier against the backend to prevent drift. It

        does not list configs or the tools actually granted to any particular config.'
      operationId: GET-V5-/v5/agent_configs/mcp_tools
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/McpTool'
                type: array
                title: Response Get-V5-/V5/Agent Configs/Mcp Tools
      x-source: https://docs.gp.scale.com/reference/v5/agent-configs/list-mcp-tool-names
components:
  schemas:
    PaginatedList_AgentConfig_:
      properties:
        object:
          type: string
          const: list
          title: Object
          default: list
        items:
          items:
            $ref: '#/components/schemas/AgentConfig'
          type: array
          title: Items
        limit:
          type: integer
          title: Limit
          description: The maximum number of items to return.
          default: 100
        total:
          type: integer
          title: Total
          description: The total of items that match the query. This is greater than or equal to the number of items returned.
        has_more:
          type: boolean
          title: Has More
          description: Whether there are more items left to be fetched.
      type: object
      required:
      - items
      - total
      - has_more
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          title: Error Type
          type: string
        input:
          title: Input
        ctx:
          type: object
          title: Context
          additionalProperties: true
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    McpTool:
      type: string
      enum:
      - Slack
      - Linear
      - GitHub
      - Confluence
      - Notion
      - Datadog
      - PagerDuty
      - Salesforce
      - Figma
      - Granola
      - Jira
      - Gmail
      - GoogleCalendar
      - GoogleDrive
      - GoogleDocs
      - GoogleSheets
      - GoogleSlides
      - Snowflake
      - Redash
      - Tableau
      - Metabase
      - Gong
      - ZoomInfo
      - Clay
      title: McpTool
      description: 'Subset of ``AllowedTool`` values that represent MCP servers.


        Single source of truth for which tool names route to MCPs (Linear,

        Notion, ...) vs harness-provided tools (Read, Bash, ...). Values must

        stay aligned with the matching ``AllowedTool`` members.


        The frontend reads this enum''s members via the generated SDK

        (``components[''schemas''][''McpTool'']``). Its own ``MCP_TOOLS`` list in

        ``egp-annotation/.../beta/build/custom/_api/constants.ts`` is asserted at

        compile time to be a SUBSET of this enum, so renaming or removing a member

        here fails the frontend typecheck. The reverse is deliberately not enforced:

        a name can exist here while the UI still hides it, which is how a server is

        staged before its OAuth flow is ready.


        Like ``AllowedTool``, this list is permissive by design. Presence here only

        means the API accepts the name; the golden agent''s catalog decides whether it

        resolves, and ``MCP_TOOLS`` decides whether it is offered.'
    RepoSpec:
      properties:
        url:
          type: string
          maxLength: 2048
          minLength: 1
          title: Url
        path:
          title: Path
          type: string
          maxLength: 1024
        depth:
          title: Depth
          type: integer
          minimum: 1
      type: object
      required:
      - url
      title: RepoSpec
      description: 'A single repo the agent should clone into its workspace.


        Mirrors the per-entry shape the golden agent''s ``_validate_repos`` accepts:

        ``url`` is required, the rest are optional passthrough hints. Sent verbatim

        as ``task.params.repos`` so provisioning clones these instead of the

        deployment-global default.'
    Harness:
      type: string
      enum:
      - claude-code
      - codex
      - litellm
      title: Harness
      description: 'Supported agent harness strategies.


        Mirrors ``PROVIDERS`` in golden-agent''s ``project/harness/activity.py``.'
    AllowedTool:
      type: string
      enum:
      - Read
      - Write
      - Edit
      - Bash
      - Glob
      - Grep
      - List
      - WebFetch
      - WebSearch
      - Task
      - TodoWrite
      - NotebookEdit
      - ExitPlanMode
      - Slack
      - Linear
      - GitHub
      - Confluence
      - Notion
      - Datadog
      - PagerDuty
      - Salesforce
      - Figma
      - Granola
      - Jira
      - Gmail
      - GoogleCalendar
      - GoogleDrive
      - GoogleDocs
      - GoogleSheets
      - GoogleSlides
      - Snowflake
      - Redash
      - Tableau
      - Metabase
      - Gong
      - ZoomInfo
      - Clay
      title: AllowedTool
      description: 'Tools an agent config may be granted.


        Granting an MCP server name (Slack, Linear, etc.) authorizes every tool

        exposed by that server, scoped via the agent''s credentials.'
    DeleteResponse_AgentConfig_:
      properties:
        id:
          type: string
          title: Id
        object:
          type: string
          const: agent_config
          title: Object
          default: agent_config
        deleted:
          type: boolean
          title: Deleted
      type: object
      required:
      - id
      - deleted
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    UpdateAgentConfigRequest:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
        description:
          title: Description
          type: string
          maxLength: 2000
        system_prompt:
          type: string
          maxLength: 100000
          minLength: 1
          title: System Prompt
        harness:
          $ref: '#/components/schemas/Harness'
        allowed_tools:
          title: Allowed Tools
          items:
            $ref: '#/components/schemas/AllowedTool'
          type: array
        model:
          type: string
          maxLength: 255
          minLength: 1
          title: Model
        persistent_workspace:
          title: Persistent Workspace
          type: boolean
        repos:
          title: Repos
          items:
            $ref: '#/components/schemas/RepoSpec'
          type: array
      type: object
      title: UpdateAgentConfigRequest
    SortOrder:
      type: string
      enum:
      - asc
      - desc
      title: SortOrder
    AgentConfig:
      properties:
        id:
          type: string
          title: Id
        object:
          type: string
          const: agent_config
          title: Object
          default: agent_config
        name:
          type: string
          title: Name
        description:
          title: Description
          type: string
        system_prompt:
          type: string
          title: System Prompt
        harness:
          type: string
          title: Harness
        allowed_tools:
          items:
            type: string
          type: array
          title: Allowed Tools
        model:
          type: string
          title: Model
        persistent_workspace:
          type: boolean
          title: Persistent Workspace
          default: false
        repos:
          title: Repos
          items:
            $ref: '#/components/schemas/RepoSpec'
          type: array
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - name
      - system_prompt
      - harness
      - allowed_tools
      - model
      - created_at
      - updated_at
    CreateAgentConfigRequest:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
        description:
          title: Description
          type: string
          maxLength: 2000
        system_prompt:
          type: string
          maxLength: 100000
          minLength: 1
          title: System Prompt
        harness:
          $ref: '#/components/schemas/Harness'
          description: Harness strategy. See Harness enum for supported values.
        allowed_tools:
          items:
            $ref: '#/components/schemas/AllowedTool'
          type: array
          title: Allowed Tools
          description: Tools enabled for this config. See AllowedTool enum for the catalogue.
        model:
          type: string
          maxLength: 255
          minLength: 1
          title: Model
        persistent_workspace:
          type: boolean
          title: Persistent Workspace
          description: Give tasks a persistent /workspace that survives sandbox death. Fixed for a task's life; defaults off.
          default: false
        repos:
          title: Repos
          description: Per-config repo override. None uses the deployment default; an empty list clones nothing.
          items:
            $ref: '#/components/schemas/RepoSpec'
          type: array
      type: object
      required:
      - name
      - system_prompt
      - harness
      - model
      title: CreateAgentConfigRequest
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
x-assembled-from: Per-operation OpenAPI fragments embedded verbatim in docs.gp.scale.com reference pages; source spec https://api.sgp.scale.com/openapi-versions/v5/openapi.json (404 when assembled)