v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Retrieve an 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.

get/api/v1/agents/{agent}

Path parameters

agentstring required

ID (agi_...) or lookup_key of the agent to retrieve.

Response

Successful response

appstring

ID of the application that owns this agent (dap_...).

created_atstring date-time

When the agent was created (ISO 8601).

default_modelstring

Default LLM model identifier used by this agent when no model is specified at runtime (e.g. "claude-3-7-sonnet-latest").

emailstring

Email address provisioned for this agent. null if email delivery is not configured.

idstring required

Agent ID (agi_...).

identitystring

System-level identity prompt that shapes the agent's persona and behavior.

last_applied_template_configstring

ID of the AgentTemplate config (cfg_...) this agent was last provisioned or updated from. null for manually created agents.

lookup_keystring

Stable, user-defined identifier for this agent within the application. Unique per app.

metadataobject

Arbitrary key-value metadata attached to the agent. Not interpreted by the platform.

namestring

Human-readable display name for the agent. null if not set.

orgstring

ID of the organization this agent belongs to (org_...). null if the agent is not org-scoped.

org_namestring

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.

originatorstring

Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).

phone_numberstring

Phone number provisioned for this agent. null if SMS is not configured.

sandboxstring

ID of the sandbox environment this agent is scoped to (dsb_...). null in production deployments.

teamstring

ID of the team that owns this agent (tem_...). null if the agent is not team-scoped.

updated_atstring date-time

When the agent was last modified (ISO 8601).

userstring

ID of the user that owns this agent (usr_...). null if the agent is not user-scoped.

Example response

{
  "acl": {
    "add": [
      {
        "actions": [
          "read",
          "write"
        ],
        "principal": "string",
        "principal_type": "user"
      }
    ],
    "grants": [
      {
        "actions": [
          "read",
          "write"
        ],
        "principal": "string",
        "principal_type": "user"
      }
    ],
    "remove": [
      {
        "principal": "string",
        "principal_type": "user"
      }
    ]
  },
  "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
  "created_at": "2024-01-01T00:00:00Z",
  "default_model": "claude-3-7-sonnet-latest",
  "email": "user@example.com",
  "id": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "identity": "You are a helpful assistant that answers questions about ArchAstro products.",
  "last_applied_template_config": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
  "lookup_key": "string",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
  "org_name": "Example Name",
  "originator": "deploy-pipeline",
  "phone_number": "+15555550123",
  "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
  "source_solution": {
    "solution": {
      "category_keys": [
        "string"
      ],
      "created_at": "2024-01-01T00:00:00Z",
      "description": "An example description.",
      "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
      "kind": "Solution",
      "latest_solution": "id_0aBcDeFgHiJkLmNoPqRsTu",
      "latest_version": "1.0.0",
      "lookup_key": "string",
      "metadata": {
        "key": "value"
      },
      "name": "Example Name",
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "org_logo": {
        "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
        "height": 600,
        "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
        "mime_type": "application/json",
        "refresh_url": "https://example.com",
        "url": "https://example.com",
        "width": 800
      },
      "org_name": "Example Name",
      "org_slug": "example-slug",
      "owners": [
        "string"
      ],
      "readme_url": "https://example.com",
      "solution_id": "01234567-89ab-cdef-0123-456789abcdef",
      "solution_version": "1.2.0",
      "tag_keys": [
        "string"
      ],
      "template_kind": "AgentTemplate",
      "templates": [
        {
          "description": "An example description.",
          "display_name": "Example Name",
          "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
          "kind": "AgentTemplate",
          "lookup_key": "string",
          "name": "Example Name",
          "readme_url": "https://example.com",
          "virtual_path": "string"
        }
      ],
      "updated_at": "2024-01-01T00:00:00Z",
      "upgrade_available": true,
      "virtual_path": "string"
    },
    "template": {
      "created_at": "2024-01-01T00:00:00Z",
      "description": "An example description.",
      "display_name": "Example Name",
      "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
      "kind": "agent_tool_template",
      "lookup_key": "string",
      "name": "Example Name",
      "updated_at": "2024-01-01T00:00:00Z",
      "virtual_path": "string"
    }
  },
  "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
  "updated_at": "2024-01-01T00:00:00Z",
  "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
}