Create a session
package main
import ( "fmt" "strings" "net/http" "io")
func main() {
url := "https://api.ai.wpengine.com/v1/sessions"
payload := strings.NewReader("{ \"agent\": \"agent_xyz\", \"title\": \"example\", \"reasoning_effort\": \"example\", \"metadata\": { \"additionalProperty\": \"example\" }, \"owner_id\": \"example\", \"site_ids\": [ \"example\" ] }")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>") req.Header.Add("Content-Type", "application/json")
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/sessions';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"agent":"agent_xyz","title":"example","reasoning_effort":"example","metadata":{"additionalProperty":"example"},"owner_id":"example","site_ids":["example"]}'};
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('POST', 'https://api.ai.wpengine.com/v1/sessions', [ 'body' => '{ "agent": "agent_xyz", "title": "example", "reasoning_effort": "example", "metadata": { "additionalProperty": "example" }, "owner_id": "example", "site_ids": [ "example" ] }', 'headers' => [ 'Authorization' => 'Bearer <token>', 'Content-Type' => 'application/json', ],]);
echo $response->getBody();curl --request POST \ --url https://api.ai.wpengine.com/v1/sessions \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "agent": "agent_xyz", "title": "example", "reasoning_effort": "example", "metadata": { "additionalProperty": "example" }, "owner_id": "example", "site_ids": [ "example" ] }'Creates a conversation session bound to an agent. The agent field accepts either a string agent id or {id, type, version}. The session inherits its project from the referenced agent. Accepts a service-token bearer authenticating a site or an API key, either of which must be authorized for the agent’s project.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
Session title.
Optional session override for reasoning effort. Allowed values are the bound agent’s current model parameters.reasoning_effort on GET /v1/models. Omit to inherit the agent’s value (then the provider default).
String key-value metadata.
object
Opaque per-visitor id of the caller creating this session, for browser-session-backed consumers (e.g. a site widget minting per-visitor browser tokens). Recorded immutably and used to enforce per-visitor ownership on this session’s events for browser session tokens. Omit when the creator has no per-visitor concept.
Sites this session may work on. Each must be a site registered in the agent’s project. Site and knowledge-base tool calls that name the session in the Agent-Session-Id header are refused for any other site, and for any knowledge base collection that is not one of these sites’ knowledge bases. Omit or send an empty array to allow every site in the project. An entry that is not such a site is rejected with 400 without saying why.
Responses
Section titled “Responses”Created session
object
object
Unique identifier for the agent.
The project the agent belongs to.
Free-form description of what the agent does. On an agent with a profile this is the profile’s current description.
User prompt template (site prompt). On an agent with a profile this is the profile’s current prompt.
Server-owned profile the agent follows (see CreateAgentRequest.profile). Omitted when the client owns every field.
Fields owned by the agent’s profile, which the client cannot write. Omitted when the agent has no profile.
Models the agent’s profile allows as a model choice. Omitted when the agent has no profile.
Output-token limit per turn (see CreateAgentRequest.max_tokens). Omitted when unset on the agent.
Catalog-native reasoning effort stored on the agent. Omitted when unset. Allowed values follow the agent’s current model on GET /v1/models.
Permission scopes the agent operates under (round-trips the request value).
Feature toggles for the agent (round-trips the request value).
object
object
Tool declarations (client tools, knowledge_base grounding entries, and echo/random_number evaluation tool opt-ins) round-tripped from the request.
object
Discriminator for the tools[] union. Omit for a plain client tool (the default); custom is the only value this schema accepts.
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.
Human-readable description of what the tool does.
JSON Schema defining the tool’s input parameters.
object
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.
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.
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
The knowledge-base collection to ground retrieval against.
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
Post types to include.
Document URIs to include.
ISO 639-1 language codes to include.
Exact-match filters keyed by metadata field; each field maps to a list of accepted values.
object
Inclusive date bounds (RFC-3339). Either bound may be omitted.
object
Inclusive date bounds (RFC-3339). Either bound may be omitted.
object
object
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.
Unique wire identifier for the tool, chosen by the caller. Must be unique within the agent’s tools array.
object
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.
Unique wire identifier for the tool, chosen by the caller. Must be unique within the agent’s tools array.
object
User-supplied string metadata. Reserved keys (“scopes”, “settings”) are surfaced on their own top-level fields rather than appearing here.
object
object
Session override for reasoning effort. Omitted when unset (the session inherits the agent’s value, then the provider default).
object
object
Cumulative billing total in nano-credits (billionths of a credit)
Opaque per-visitor id recorded at creation, when the creator supplied one. Absent for sessions created without per-visitor attribution.
Sites this session may work on, sorted. Empty when every site in the project is allowed.
Example
{ "type": "session", "agent": { "type": "agent", "managed_fields": [ "model", "system_prompt", "description" ], "tools": [ { "type": "custom", "defer_loading": false } ] }, "status": "idle"}Invalid request body or parameters
object
object
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.
Example
{ "error": { "type": "invalid_request_error", "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5" }}Missing or invalid bearer token
object
object
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.
Example
{ "error": { "type": "invalid_request_error", "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5" }}Headers
Section titled “Headers”Example
Bearer realm="ai-services"The token is valid, but the request is forbidden. Error type “permission_error” means the token’s scope/permission is insufficient or the authenticated user is not authorized for the target account; “entitlement_required” means the account lacks the required product entitlement; and “account_required” means no billing account could be resolved. On /v1/chat/completions when content moderation is enabled, and on /v1/sessions/{session_id}/events, 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.
object
object
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.
Example
{ "error": { "type": "invalid_request_error", "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5" }}Request body exceeds the 64 KiB limit
object
object
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.
Example
{ "error": { "type": "invalid_request_error", "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5" }}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.
object
object
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.
Example
{ "error": { "type": "invalid_request_error", "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5" }}A required dependency is temporarily unavailable. Retry after a short delay with exponential back-off. An entitlement lookup failure uses error type “entitlement_unavailable”.
object
object
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.
Example
{ "error": { "type": "invalid_request_error", "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5" }}