---
title: "Retrieve an agent"
method: GET
path: "/api/v1/agents/{agent}"
---

# Retrieve an agent

`GET /api/v1/agents/{agent}`

Returns the agent identified by ID or `lookup_key`. The authenticated caller must
own the agent or hold sufficient permissions within its owning org or team.

When called under a developer app scope, the agent must belong to that app. Use the
list endpoint to retrieve many agents at once.

## Path parameters

- `agent` string, required

## Response `200`

Successful response

- Agent — An AI agent that can be configured with tools, routines, and skills, and invoked to handle conversations or tasks.
  - `acl` Acl — An access-control list payload that supports either full replacement or targeted patch operations on a resource's grants.
    - `add` AclGrant[] — Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.
      - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
      - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.
      - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
    - `grants` AclGrant[] — Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`.
      - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
      - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.
      - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
    - `remove` AclRemoveTarget[] — Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.
      - `principal` string — The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.
      - `principal_type` string, required — The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
  - `app` string — ID of the application that owns this agent (`dap_...`).
  - `created_at` string, date-time — When the agent was created (ISO 8601).
  - `default_model` string — Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `"claude-3-7-sonnet-latest"`).
  - `email` string — Email address provisioned for this agent. `null` if email delivery is not configured.
  - `id` string, required — Agent ID (`agi_...`).
  - `identity` string — System-level identity prompt that shapes the agent's persona and behavior.
  - `last_applied_template_config` string — ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.
  - `lookup_key` string — Stable, user-defined identifier for this agent within the application. Unique per app.
  - `metadata` object — Arbitrary key-value metadata attached to the agent. Not interpreted by the platform.
  - `name` string — Human-readable display name for the agent. `null` if not set.
  - `org` string — ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.
  - `org_name` string — Display name of the organization this agent belongs to. `null` when the agent is not org-scoped or when the org association was not preloaded.
  - `originator` string — Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).
  - `phone_number` string — Phone number provisioned for this agent. `null` if SMS is not configured.
  - `sandbox` string — ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.
  - `source_solution` AgentSourceSolution — Summary of the Solution and AgentTemplate that an agent was last provisioned from. Returned on single-agent responses; `null` for hand-built agents and agents whose tracked template or parent Solution has been deleted.
    - `solution` SolutionSummary, required — A catalog entry for an imported Solution, including its display metadata, bundled templates, owner scopes, and any available upgrade information.
      - `category_keys` string[] — Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.
      - `created_at` string, date-time — When the Solution config was first imported (ISO 8601).
      - `description` string — Short tagline or summary declared in the Solution body, used as the card subhead in catalog UIs. `null` when the Solution body does not set one.
      - `id` string, required — Solution config ID (`cfg_...`).
      - `kind` string, required — Resource type. Always `"Solution"`.
      - `latest_solution` string — When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.
      - `latest_version` string — When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.
      - `lookup_key` string — The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.
      - `metadata` object — Arbitrary key-value metadata declared in the Solution body (e.g. category or display hints). Present as an empty object when the body declares none.
      - `name` string — Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.
      - `org` string — Organization ID (`org_...`) that owns this Solution config, when the Solution is scoped to a specific org. `null` for system-scope (app-level) Solutions.
      - `org_logo` ImageSource — Resolved metadata for an image, including its delivery URL, dimensions, and optional references to the underlying storage file or media record.
        - `file` string — ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.
        - `height` integer — Height of the image in pixels. `null` if not known.
        - `media` string — ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.
        - `mime_type` string — MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.
        - `refresh_url` string — Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.
        - `url` string — Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.
        - `width` integer — Width of the image in pixels. `null` if not known.
      - `org_name` string — Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.
      - `org_slug` string — Resolved slug of the Solution body's `org` (the publishing organization), when set and it resolves to a real org visible to the viewer. When present this is the Solution's principal catalog category key — clients group the Solution under this org ahead of `category_keys`. `null` when the body has no `org` or it doesn't resolve.
      - `owners` string[], required — Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer's org scope).
      - `readme_url` string — Relative path to the public README endpoint with a signed token already embedded. `null` when the Solution has no README. Token expires in 1 hour — refresh via `GET /api/v1/solutions/:solution`.
      - `solution_id` string — Stable UUID declared in the Solution body, used to identify the same logical Solution across multiple installed copies and owner scopes. `null` when the body omits it.
      - `solution_version` string — Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version.
      - `tag_keys` string[] — Freeform tag keys declared in the Solution body. An empty array when the body declares none.
      - `template_kind` string — Wrapped template kind — `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles.
      - `templates` SolutionTemplateSummary[], required — Template configs bundled by this Solution, in declaration order — the first entry is the deployable template the Solution wraps; the rest are sibling templates the wrapped template references.
        - `description` string — Short prose blurb from the template body's `description:` field. `null` when the body doesn't set one. Used as the card subhead in the Library carousel.
        - `display_name` string — Human-facing label from the template body's `display_name:` field. `null` when the body doesn't set one. Library carousels use this for the card title, falling back to a humanized `name`.
        - `id` string — Template config ID (`cfg_...`). `null` for inline-only templates.
        - `kind` string, required — Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.
        - `lookup_key` string — Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.
        - `name` string — Canonical name from the template body. For `AgentTemplate` this doubles as the human-facing label; for `AgentToolTemplate` it's the LLM-facing tool function identifier (snake_case); for `AgentRoutineTemplate` it's the routine identifier (kebab-case). Clients rendering carousels should prefer `display_name` and fall back to humanizing `name`.
        - `readme_url` string — Relative path to the public README endpoint with a signed token already embedded, scoped to this template's bundled markdown asset. `null` when the Solution body's `templates[].readme_path` is unset for this entry. Token expires in 1 hour — refresh via `GET /api/v1/solutions/:solution`.
        - `virtual_path` string — Stable virtual path assigned to the template config. `null` when no virtual path was set.
      - `updated_at` string, date-time — When the Solution config was last modified (ISO 8601).
      - `upgrade_available` boolean, required — `true` when this Solution is installed at the viewer's org scope and the app-level system scope carries a higher `solution_version`. Always `false` for system-only rows.
      - `virtual_path` string — The stable virtual path assigned to this Solution config, used as the deduplication key when the same Solution appears under multiple owner scopes. `null` when unset.
    - `template` UpgradeTemplateSummary, required — Compact summary of an AgentTemplate config referenced by an agent upgrade or source-solution response.
      - `created_at` string, date-time — When this template config was created (ISO 8601).
      - `description` string — Description of the template from the config body. `null` if the current version has no `description` field.
      - `display_name` string — Human-readable display name from the config body. `null` if the current version has no `display_name` field.
      - `id` string, required — Template config ID (`cfg_...`).
      - `kind` string, required — Config kind identifier for this template (e.g. `"agent_tool_template"`).
      - `lookup_key` string — Stable lookup key assigned to this template config. `null` if no lookup key is set.
      - `name` string — Template name as stored in the config body. `null` if the current version has no `name` field.
      - `updated_at` string, date-time — When this template config was last modified (ISO 8601).
      - `virtual_path` string — Virtual filesystem path for this template config. `null` if not set.
  - `team` string — ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.
  - `updated_at` string, date-time — When the agent was last modified (ISO 8601).
  - `user` string — ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.

## Other responses

- `401` — Unauthorized
- `403` — Forbidden - app scope required
- `404` — Agent not found

---

[API](https://skmtc.net/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.net/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/versions/a8772b442f86/schema)