> ## 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 all agents of an organization (admin) > Org-wide agent listing for administrators (agent-factory admin or platform admin), whatever the owner or visibility. The caller must belong to `orgSlug`. Rows expose the published snapshot when one exists and never carry `published_config`. Sorted descending. ## OpenAPI ````yaml /api-reference/agent-factory/swagger.yml get /v1/orgs/{orgSlug}/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: Traces description: >- Execution traces of agent turns (editor debugging, `agent-factory:traces:read`). - name: Evaluations description: Agent evaluation runs and results. - name: Admin description: | GDPR operations called by the AI Insights admin screens. They require elevated permissions: the caller must be a platform administrator (`platformRole` `superadmin` or `root`). The export route also lets a user export their own data. Each route is rate limited to 10 calls per hour per caller. paths: /v1/orgs/{orgSlug}/agents: get: tags: - Agents summary: List all agents of an organization (admin) description: | Org-wide agent listing for administrators (agent-factory admin or platform admin), whatever the owner or visibility. The caller must belong to `orgSlug`. Rows expose the published snapshot when one exists and never carry `published_config`. Sorted descending. operationId: listOrgAgents parameters: - name: orgSlug in: path required: true schema: type: string maxLength: 64 - name: status in: query required: false schema: type: string maxLength: 32 - name: search in: query required: false schema: type: string maxLength: 200 description: Case-insensitive match on name or description. - name: last_message_after in: query required: false schema: type: string maxLength: 40 description: ISO date - only agents with a message at or after this date. - name: last_message_before in: query required: false schema: type: string maxLength: 40 description: >- ISO date - agents with no message since this date (never-used agents included). - name: min_messages in: query required: false schema: type: string description: Minimum `messages_count`. - name: created_before in: query required: false schema: type: string maxLength: 40 description: ISO date - only agents created before this date. - name: sort in: query required: false schema: type: string enum: - created - last_message - messages description: Sort field, always descending (default `created`). - 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 the org's agents. content: application/json: schema: $ref: '#/components/schemas/AgentListResponse' '401': description: Authentication required. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Forbidden - not a member of this org, or not an agent-factory / platform admin. content: application/json: schema: $ref: '#/components/schemas/Error' '405': description: Method not allowed (only GET is accepted). 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 attachments: type: object readOnly: true description: | Where to upload an attachment before referencing it in `message.parts[].url`: `POST {url}` in multipart, then put the returned file `url` in the part. This is the storage workspace, the one the web chat uploads to; clients should read it here rather than hardcode a workspace. properties: upload: type: object properties: workspaceId: type: string description: > Workspace reference usable as-is in a `/workspaces/{workspaceId}` path. Currently the slug form `slug:storage`, not a raw id. url: type: string format: uri method: type: string enum: - POST 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 effective_defaults: type: object description: > Editor view only (x-draft-mode, caller with edit rights). The values the runtime applies when an advanced field is left empty: profile limits first, then the workspace defaults (max_turns has no profile default: the workspace default applies, 50 when unset); max_tokens is the model's declared response limit, or null when the provider drops max_tokens (its own default applies). temperature_ignored is true when the model's provider drops the temperature parameter. properties: temperature: type: number temperature_ignored: type: boolean max_tokens: type: integer nullable: true 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. role: type: string enum: - owner - admin - editor - reader - null nullable: true description: | The CALLER's effective rights on this agent, computed at read time. It has the same shape as `role` on knowledge bases. Returned by `GET /v1/agents/{agent_id}` and by the list endpoint. - `owner` - owns the agent. - `admin` - platform admin, agent-factory admin in the agent's org, or a share carrying the owner/admin role. Implies publish rights. - `editor` - may write but NOT publish. A surface rendering a *publish* button must check for `admin`, not merely "not reader". - `reader` - a decision was taken and it grants no write. - `null` - UNDETERMINED, **not** a refusal: for a caller who is neither owner nor admin, the write decision is only taken when the request asks for it - `x-draft-mode` on the detail endpoint, `x-draft-mode` or `?action=write` on the list. A consumer read (chat, embed, A2A, MCP) pays for no probe and gets null. Render no access screen on null - re-ask with the header, or show the consumer view. Reading an agent is much wider than editing it (a published+public agent is readable org-wide), which is why Agent Creator gates its UI on this rather than on the global `agent-factory:agents:write` scope. Informational - write endpoints still authorize on their own. access_reason: type: string description: >- Which access path granted the read: `owner`, `admin`, `public`, `published`, `trusted-source:`, `binding:[:]`, `wildcard-scope`, `scope` or `permission`. Diagnostic companion to `role`, and internal authorization topology - so it rides with the editor surface only: `GET /v1/agents/{agent_id}` returns it when the request carries `x-draft-mode`, and never on a consumer read or in the list. The `binding:` prefix carries a second job: it is what lets an agent with no published version be served to someone it was explicitly shared with - never published or withdrawn alike, since withdrawing empties the catalogue and not the shares. A public consumer (`public`), an admin (`admin`) and an RBAC scope (`wildcard-scope`, `scope`) do not match it and keep the refusal. is_owner: type: boolean description: >- Whether the caller owns this agent. Redundant with `role` = `owner`, kept for surfaces that only need that one bit. 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, then auto-approve that tool for the rest of the session. The approval is cached per tool (the namespaced `__` name for an MCP child) whatever level the rule is written at: under an MCP server rule, approving one child does not approve its siblings. When the matched rule carries `conditions`, the approval is also scoped to those conditions (e.g. `records` with `action: delete` is approved apart from `records` itself). 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. A matching conditional rule beats a rule without `conditions` on the same tool, whatever their order in the array; when no conditional rule matches, the call falls through to the tool's rule without `conditions`, then to a legacy rule on the bare tool name, then to the server's rule, then to `default`. 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_...`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.