create_agent_key
const url = 'https://app.everruns.com/api/v1/agents/example/channels/example/keys';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"expires_at":"2026-04-15T12:00:00Z","name":"Support backend"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://app.everruns.com/api/v1/agents/example/channels/example/keys \ --header 'Content-Type: application/json' \ --data '{ "expires_at": "2026-04-15T12:00:00Z", "name": "Support backend" }'Create an agent key for an agent’s API channel. The secret is in this response only.
Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”Agent ID or name
API channel ID
Request Bodyrequired
Section titled “Request Bodyrequired”Request to create an agent key.
object
When the key stops working. Omit for no expiry.
Display name, e.g. the application that holds the key.
Example
Support backendResponses
Section titled “ Responses ”Key created
A key with its secret, returned once by create and rotate.
object
The api channel the key calls.
When the key stops working, if ever.
Key id (agentkey_…). Stable across rotations.
Last successful use (updated at most once a minute).
Display name.
What the key may do.
Non-secret display prefix of the current secret.
Until when the secret replaced by the last rotation still works.
When the key was revoked; a revoked key never works again.
The secret. Shown only in this response; store it now.
Example
{ "channel_id": "appchan_01933b5a000070008000000000000001", "id": "agentkey_01933b5a000070008000000000000001", "name": "Support backend", "permissions": [ "sessions" ], "prefix": "evr_ak_1a2b3c4d...", "secret": "evr_ak_1a2b3c4d5e6f…"}Invalid request
Standard error response.
Wire shape is RFC 9457 Problem Details:
every error response includes title and status, and may include
detail, code, allowed_actions, retry_after_seconds, instance,
and type. The content type is rewritten to application/problem+json
with the application/problem+json content type.
object
Recovery actions the caller can take next.
Agent-actionable link describing a follow-up the caller can take. Used in two contexts:
- Error recovery —
ErrorResponse.allowed_actionscarriesrels likeretry,retry-later,unarchive,get-existingso the agent knows the right next call after a 4xx/429. - Entity hypermedia —
WithUrls<T>.allowed_actionscarries state-awarerels likecancel,events,self,updateon the entity itself so the agent can follow links instead of reconstructing routes from prose.
The shape is intentionally identical across both contexts; the closed
rel vocabulary distinguishes them.
object
Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).
Absolute (preferred) or relative URL the caller may invoke
directly. Always present on entity hypermedia actions
(WithUrls<T>.allowed_actions); optional on error-recovery
actions (ErrorResponse.allowed_actions) where the matching
operation_id is enough and the URI is implicit from the failed
call.
HTTP method to use against href. Required for entity hypermedia
actions; usually omitted on error-recovery actions where the same
operation is retried with its original method.
OpenAPI operationId the caller should invoke. Lets an MCP client
resolve the call without parsing href.
Link relation describing the action. Examples: self, cancel, pause,
resume, events, retry, retry-later, unarchive,
get-existing, delete, update.
OpenAPI $ref to the request-body schema, when the action takes one
(e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling
agent fetch the input shape without scanning the whole spec.
Stable, machine-readable error code (snake_case).
Human-readable explanation specific to this occurrence.
Request URI for this occurrence.
Seconds the caller should wait before retrying (429 / transient 503).
HTTP status code; mirrors the response status line.
Short, human-readable summary of the problem (e.g. “Not Found”).
RFC 9457 problem type URI. Optional; identifies the problem class.
Example
{ "allowed_actions": [ { "method": "POST" } ], "code": "session_not_found", "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.", "instance": "/v1/sessions/session_01933b5a000070008000000000000001", "retry_after_seconds": 30, "status": 404, "title": "Session not found", "type": "https://docs.everruns.com/errors/session_not_found"}Agent or API channel not found
Standard error response.
Wire shape is RFC 9457 Problem Details:
every error response includes title and status, and may include
detail, code, allowed_actions, retry_after_seconds, instance,
and type. The content type is rewritten to application/problem+json
with the application/problem+json content type.
object
Recovery actions the caller can take next.
Agent-actionable link describing a follow-up the caller can take. Used in two contexts:
- Error recovery —
ErrorResponse.allowed_actionscarriesrels likeretry,retry-later,unarchive,get-existingso the agent knows the right next call after a 4xx/429. - Entity hypermedia —
WithUrls<T>.allowed_actionscarries state-awarerels likecancel,events,self,updateon the entity itself so the agent can follow links instead of reconstructing routes from prose.
The shape is intentionally identical across both contexts; the closed
rel vocabulary distinguishes them.
object
Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).
Absolute (preferred) or relative URL the caller may invoke
directly. Always present on entity hypermedia actions
(WithUrls<T>.allowed_actions); optional on error-recovery
actions (ErrorResponse.allowed_actions) where the matching
operation_id is enough and the URI is implicit from the failed
call.
HTTP method to use against href. Required for entity hypermedia
actions; usually omitted on error-recovery actions where the same
operation is retried with its original method.
OpenAPI operationId the caller should invoke. Lets an MCP client
resolve the call without parsing href.
Link relation describing the action. Examples: self, cancel, pause,
resume, events, retry, retry-later, unarchive,
get-existing, delete, update.
OpenAPI $ref to the request-body schema, when the action takes one
(e.g. #/components/schemas/UpdateSessionRequest). Lets a tool-calling
agent fetch the input shape without scanning the whole spec.
Stable, machine-readable error code (snake_case).
Human-readable explanation specific to this occurrence.
Request URI for this occurrence.
Seconds the caller should wait before retrying (429 / transient 503).
HTTP status code; mirrors the response status line.
Short, human-readable summary of the problem (e.g. “Not Found”).
RFC 9457 problem type URI. Optional; identifies the problem class.
Example
{ "allowed_actions": [ { "method": "POST" } ], "code": "session_not_found", "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.", "instance": "/v1/sessions/session_01933b5a000070008000000000000001", "retry_after_seconds": 30, "status": 404, "title": "Session not found", "type": "https://docs.everruns.com/errors/session_not_found"}