Retrieve an agent

GET

/v1/agents/{agent_id}

package main

import (
  "fmt"
  "net/http"
  "io"
)

func main() {

  url := "https://api.ai.wpengine.com/v1/agents/example"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <token>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

const url = 'https://api.ai.wpengine.com/v1/agents/example';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.ai.wpengine.com/v1/agents/example', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();

Returns a single agent. The agent_id is the identifier returned by POST /v1/agents. Accepts a service-token bearer authenticating a site or an API key, either of which must be authorized for the agent’s project. Returns 404 when the agent does not exist or the caller isn’t authorized for its project (the same response shape is used in both cases, so callers cannot probe IDs across tenants).

Authorizations

bearerAuth

Parameters

Path Parameters

agent_id

required

string

The agent ID.

Responses

200

The requested agent

application/json

object

required

Unique identifier for the agent.

string

type

required

string

Allowed values: agent

project_id

required

The project the agent belongs to.

string

name

required

string

model

required

string

description

string

system_prompt

User prompt template (site prompt).

string

temperature

number format: float

max_tokens

Output-token limit per turn (see CreateAgentRequest.max_tokens). Omitted when unset on the agent.

integer

reasoning_effort

Catalog-native reasoning effort stored on the agent. Omitted when unset. Allowed values follow the agent’s current model on GET /v1/models.

string

scopes

Permission scopes the agent operates under (round-trips the request value).

Array<string>

settings

Feature toggles for the agent (round-trips the request value).

object

key

additional properties

any

mcp_servers

Array<object>

object

key

additional properties

any

tools

Tool declarations (client tools, knowledge_base grounding entries, and echo/random_number evaluation tool opt-ins) round-tripped from the request.

Array

One of: discriminator: type

object

type

Discriminator for the tools[] union. Omit for a plain client tool (the default); custom is the only value this schema accepts.

string

Allowed values: custom

name

Unique tool name. Must be unique within the agent’s tools array (across every entry, regardless of type). Always present for tools created since name validation was added; may be absent on an agent whose tools were stored before that validation existed.

string

<= 64 characters /^[a-zA-Z0-9_-]{1,64}$/

description

Human-readable description of what the tool does.

string

input_schema

JSON Schema defining the tool’s input parameters.

object

label

Optional short human-readable name for the tool, used alongside name and description when the gateway matches a search query against deferred tools. Supply it when the tool’s name is a slug whose wording a natural-language query would not contain.

string

<= 64 characters

defer_loading

When true, the tool is declared but kept out of the model’s tool list until it is needed, so a large catalogue costs no context up front. The gateway offers the agent a search over the deferred tools and loads the matches, and a deferred tool the model names directly is loaded on demand. Once loaded, its input is enforced strictly against its schema — unlike a non-deferred tool, which keeps today’s lenient handling — so a malformed call is rejected with a model-readable error instead of failing downstream. Leave false (the default) for tools that must be callable from the first turn.

boolean

A data-source declaration — one entry per collection. The gateway fans it into every runtime tool it currently supports over the collection (search, fetch, …) and names them by convention from collection_id.

object

type

required

string

Allowed values: knowledge_base

collection_id

required

The knowledge-base collection to ground retrieval against.

string

filters

Optional filter ceiling scoped to this collection. Null or omitted means unconstrained. Applies to every runtime tool the gateway emits from this entry — search results are constrained to matching docs, and a fetched doc that fails any dimension comes back as not_found.

object

type

Post types to include.

Array<string>

uri

Document URIs to include.

Array<string>

language

ISO 639-1 language codes to include.

Array<string>

metadata

Exact-match filters keyed by metadata field; each field maps to a list of accepted values.

object

key

additional properties

Array<string>

created_at

Inclusive date bounds (RFC-3339). Either bound may be omitted.

object

gte

string format: date-time

lte

string format: date-time

modified_at

Inclusive date bounds (RFC-3339). Either bound may be omitted.

object

gte

string format: date-time

lte

string format: date-time

object

type

required

Opts the agent into the gateway’s built-in echo tool (returns its input message unchanged). A local development aid for validating tool-call round-trips; it is only served in dev environments, where an agent declaring it elsewhere fails at session start with a toolset_incomplete error instead. Do not declare it on an agent you intend to run outside dev.

string

Allowed values: echo

name

required

Unique wire identifier for the tool, chosen by the caller. Must be unique within the agent’s tools array.

string

<= 64 characters /^[a-zA-Z0-9_-]{1,64}$/

object

type

required

Opts the agent into the gateway’s built-in random-number tool (returns an integer within a caller-given range). A local development aid for validating tool-call round-trips; it is only served in dev environments, where an agent declaring it elsewhere fails at session start with a toolset_incomplete error instead. Do not declare it on an agent you intend to run outside dev.

string

Allowed values: random_number

name

required

Unique wire identifier for the tool, chosen by the caller. Must be unique within the agent’s tools array.

string

<= 64 characters /^[a-zA-Z0-9_-]{1,64}$/

skills

Array<object>

object

key

additional properties

any

metadata

User-supplied string metadata. Reserved keys (“scopes”, “settings”) are surfaced on their own top-level fields rather than appearing here.

object

key

additional properties

string

<= 512 characters

created_at

required

string format: date-time

updated_at

string format: date-time

nullable

Example

{
  "type": "agent",
  "tools": [
    {
      "type": "custom",
      "defer_loading": false
    }
  ]
}

400

Invalid request body or parameters

application/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

401

Missing or invalid bearer token

application/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

Headers

WWW-Authenticate

string

Example

Bearer realm="ai-services"

403

The token is valid, but the caller is not permitted to perform this action — either its scope/permission is insufficient or the authenticated user is not authorized for the target account (error type “permission_error”). On /v1/chat/completions specifically, a 403 with error type “content_policy_violation” instead means the request content was blocked by content moderation policy; that response never identifies which filter or category matched.

application/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

404

The requested resource was not found

application/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

429

Rate limit exceeded. The request was throttled at the edge; wait and retry later. The response body is a short HTML page generated by the load balancer, not a structured JSON error — clients should rely on the 429 status code rather than parsing the body.

text/html

string

500

The server encountered an unexpected error while handling the request. Safe to retry once; if it persists, the cause is server-side and the request payload was not the problem.

application/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

503

A required dependency is temporarily unavailable. Retry after a short delay with exponential back-off.

application/json

object

error

required

object

message

required

string

type

required

string

code

required

integer

request_id

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}

Platforms

Product Extensions

Plugins

Tools

Retrieve an agent

Authorizations

Parameters

Path Parameters

Responses

200

Example

400

Example

401

Example

Headers

Example

403

Example

404

Example

429

500

Example

503

Example