> ## Documentation Index > Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt > Use this file to discover all available pages before exploring further. # List agents > List agents with multi-scope filter. Supported scopes (comma-separated): `own`, `shared`, `published`, `all`. Default `own`. The reserved action `?action=explore` returns all public+restricted published agents in the caller's organization. ## OpenAPI ````yaml /api-reference/agent-factory/swagger.yml get /v1/agents openapi: 3.0.3 info: version: 1.0.0 title: Agent Factory API description: | Public REST API for the Agent Factory workspace - agents, conversations, messages, tools, artifacts, sharing, ratings, and discovery. Powered by Prisme.ai's runtime; all endpoints are exposed under each workspace's webhook namespace. contact: name: Prisme.ai url: https://prisme.ai servers: - url: https://{host}/v2/workspaces/slug:agent-factory/webhooks description: Prisme.ai workspace webhooks variables: host: default: api.studio.prisme.ai description: API host (override for self-hosted or sandbox) security: - BearerAuth: [] - OrgApiKeyAuth: [] tags: - name: Agents description: Agent CRUD, discovery, AGENTS.md import/export. - name: Access description: Agent access bindings, sharing, and access requests. - name: ApiKeys description: Agent-scoped API key management (mint, revoke, rotate). - name: Publishing description: Publish or discard draft changes on an agent. - name: Ratings description: User ratings on published agents. - name: Profiles description: >- Agent profiles/presets catalog (simple, workflow, agent_light, agent_full, orchestrator). - name: Activity description: Activity feed for agents (events, errors, lifecycle changes). - name: Analytics description: Agent usage analytics (series + summary). - name: Conversations description: Conversations on an agent (CRUD, archive, star). - name: Messages description: Send messages to an agent (synchronous send + SSE stream). - name: Tasks description: Async task lifecycle (list, fetch, cancel, resolve, subscribe). - name: Artifacts description: Generated artifacts (files, code, content) attached to a task. - name: Shares description: Conversation, message, and artifact share-link snapshots. - name: A2A description: Agent-to-agent JSON-RPC 2.0 gateway (well-known agent.json + RPC). - name: Tools description: Per-agent tool catalogue (system tools, MCP servers, function tools). - name: Retention description: Per-agent and org-wide conversation retention policies. - name: Evaluations description: Agent evaluation runs and results. paths: /v1/agents: get: tags: - Agents summary: List agents description: | List agents with multi-scope filter. Supported scopes (comma-separated): `own`, `shared`, `published`, `all`. Default `own`. The reserved action `?action=explore` returns all public+restricted published agents in the caller's organization. operationId: listAgents parameters: - name: scope in: query required: false schema: type: string maxLength: 64 description: Comma-separated list (`own`, `shared`, `published`, `all`). - name: action in: query required: false schema: type: string maxLength: 32 enum: - explore - write description: >- Reserved action (`explore` for store-style discovery, `write` to filter to writable scope). - name: status in: query required: false schema: type: string maxLength: 32 - name: category in: query required: false schema: type: string maxLength: 128 - name: search in: query required: false schema: type: string maxLength: 200 - name: sort in: query required: false schema: type: string maxLength: 32 enum: - updatedAt - createdAt - name: limit in: query required: false schema: type: string description: Page size (max 100, default 20). - name: page in: query required: false schema: type: string description: 1-indexed page number. responses: '200': description: Page of agents (with `published_config` stripped on list rows). content: application/json: schema: $ref: '#/components/schemas/AgentListResponse' '400': description: Invalid arguments. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/Error' '405': description: Method not allowed. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: AgentListResponse: type: object description: Page of agents (with `published_config` stripped on list rows). properties: items: type: array items: $ref: '#/components/schemas/Agent' total: type: integer page: type: integer limit: type: integer Error: type: object required: - error - message properties: error: type: string description: >- Stable PascalCase or SNAKE_CASE error code (e.g. AgentNotFound, VALIDATION_ERROR, FORBIDDEN, METHOD_NOT_ALLOWED). message: type: string description: Human-readable error message. details: type: object description: Optional structured context for the error. additionalProperties: true Agent: type: object description: | Agent record (full view). Owners see this complete record including `published_config`. Non-owners with binding receive the same shape with `published_config` stripped server-side. Restricted-agent rows additionally carry `access_status` (`granted` or `none`) when seen in list/discovery views. additionalProperties: true properties: id: type: string name: type: string description: type: string instructions: type: string model: type: string fallback_models: type: array items: type: string temperature: type: number icon_url: type: string skills: type: array items: type: object additionalProperties: true tools: type: array items: $ref: '#/components/schemas/Tool' tool_permissions: $ref: '#/components/schemas/ToolPermissions' tool_activation: $ref: '#/components/schemas/ToolActivation' guardrails: type: object additionalProperties: true sub_agents: type: array items: $ref: '#/components/schemas/SubAgentRef' starters: type: array items: type: object additionalProperties: true allowed_models: type: array items: type: string max_tokens: type: integer max_turns: type: integer token_budget: type: integer tool_call_budget: type: integer canvas_enabled: type: boolean visibility: type: string enum: - public - private - restricted category: type: string tags: type: array items: type: string status: type: string enum: - draft - published profile: type: string enum: - simple - workflow - agent_light - agent_full - orchestrator owner_id: type: string orgSlug: type: string subscription_id: type: string serviceAccountId: type: string published_config: type: object additionalProperties: true description: Snapshot of runtime fields at last publish (owners only). published_at: type: string format: date-time has_draft_changes: type: boolean rating: type: number ratings_count: type: integer messages_count: type: integer conversations_count: type: integer access_status: type: string enum: - granted - none description: Only present on restricted-agent rows in list/discovery views. createdAt: type: string format: date-time updatedAt: type: string format: date-time Tool: type: object description: | Tool entry attached to an agent. Discriminated by `type` - `file_search` (requires `vector_store_id`), `mcp` (uses `server`, `headers`, `scope`), or `function` (uses `url`, `parameters`, `headers`). additionalProperties: true properties: id: type: string type: type: string enum: - file_search - mcp - function name: type: string pattern: ^[a-zA-Z0-9_-]+$ display_name: type: string description: type: string catalog_id: type: string auth: type: object additionalProperties: true icon_url: type: string vector_store_id: type: string description: Required for `file_search`. server: type: string description: MCP server URL (for `mcp`). headers: type: object additionalProperties: true scope: type: string url: type: string description: Required for `function`. parameters: type: object additionalProperties: true description: JSON Schema describing the function tool's parameters. ToolPermissions: type: object description: | Human-in-the-Loop configuration. Sets a default policy plus optional per-tool overrides. Policies: - `auto`: run immediately (default). - `always_ask`: halt every call on approval. - `ask_external`: halt only on MCP tool calls. - `ask_first`: halt the first time a tool runs in a session; cache keyed per child name unless an MCP parent rule is configured (then cached per parent). properties: default: type: string enum: - auto - always_ask - ask_external - ask_first default: auto tools: type: array items: $ref: '#/components/schemas/ToolPermissionRule' ToolActivation: type: object description: | Controls whether the model can use a given tool on a given turn. `user_first` tools are replaced by a same-named, schema-less stub with a "disabled" description on each turn, unless the user explicitly summons the tool from the chat input via `metadata.tool_choice`. Eligible tool types: `function` and `mcp`. `file_search`, `skill`, `guardrail`, and `system` types are exempt and always behave as `auto`. properties: default: type: string enum: - auto - user_first default: auto tools: type: array items: $ref: '#/components/schemas/ToolActivationRule' SubAgentRef: type: object description: Sub-agent delegation entry on an agent. properties: agent_id: type: string name: type: string description: type: string ToolPermissionRule: type: object description: | Per-tool override on the default policy. Targets a function tool by name, or an MCP server by its parent name (the rule then cascades to every child tool the server exposes at runtime; a child-name rule wins over a parent rule on conflict). properties: tool: type: string policy: type: string enum: - auto - always_ask - ask_external - ask_first conditions: type: object description: | Optional `jsonmatch` pattern compared against the tool call's arguments. The rule's policy only fires when the pattern matches; otherwise the call runs without prompting. additionalProperties: true approvers: type: array items: $ref: '#/components/schemas/Approver' required: - tool - policy ToolActivationRule: type: object description: | Per-tool override on the default activation. Targets a function tool by name, or an MCP server by its parent name (activation cascades to every child tool the server exposes at runtime). properties: tool: type: string activation: type: string enum: - auto - user_first required: - tool - activation Approver: type: object description: | Designated reviewer for a `tool_permissions` rule. When at least one approver is set, the platform emits a `task.approval.required` event and the approval is resolved through `POST /v1/agents/{agent_id}/tasks/{task_id}/resolve` by anyone matching the entry. Validation rejects unknown `type` values or `user`/`group` entries missing an `id`; it does NOT verify that the referenced principal exists. properties: type: type: string enum: - owner - user - group id: type: string description: Required for `user` and `group`. Ignored for `owner`. required: - type securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: | User-bound credential carrying an identity: either a session JWT or a user access token (`at:*`) generated from the user settings UI. Send as `Authorization: Bearer `. Org API keys (`iak_*`) are **not** accepted here - they carry no user identity. Use the `x-prismeai-api-key` header instead (see `OrgApiKeyAuth`). OrgApiKeyAuth: type: apiKey in: header name: x-prismeai-api-key description: | Organization API key (`iak_{orgSlug}_{uuid}`). Unlike `Authorization: Bearer`, this credential is **not** tied to a user identity - it is bound to the org and its effective access is defined by the scopes / permission rules attached to it (it can be restricted to a single project, or kept broader). For Agent Factory, these keys can be generated directly from the Agent Factory UI (in addition to the AI Governance settings). Send as `x-prismeai-api-key: iak_...`. ````