Plainrouter Agent Context API
The AgentContext API from Plainrouter — 1 operation(s) for agentcontext.
The AgentContext API from Plainrouter — 1 operation(s) for agentcontext.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/plainrouter:plainrouter-agentcontext-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Plainrouter Conversion Agent Context API
version: 0.5.0
description: Plainrouter public Signals Conversion API.
servers:
- url: https://plainrouter.com/api/v1
description: Production
security:
- workspaceSecret: []
tags:
- name: AgentContext
paths:
/agent/context:
get:
operationId: agent.context
description: Read the authenticated agent and authorized account. With no active account, returns null and connection next steps.
summary: Get agent context
tags:
- AgentContext
parameters:
- name: account_id
in: query
description: Optional positive account ID. A bound key may name only its own account; a different ID returns 422. An unbound key requires exactly one active available advertising account with an active connection; omission uses that account and a supplied ID must match it. Multiple active accounts return 422 even when account_id is supplied. With no active available account, a valid account_id is ignored and platform_ad_account is null.
schema:
type: integer
minimum: 1
- name: workspace_id
in: query
description: Optional workspace grant selector. Required for credentials with multiple workspace grants; it must identify an authorized workspace.
schema:
type: integer
minimum: 1
responses:
'200':
description: Agent identity and account context.
content:
application/json:
schema:
type: object
properties:
meta_connected:
type: boolean
agent:
type: object
properties:
id:
type: string
name:
type: string
scopes:
type: array
items:
type: string
authentication:
type: string
enum:
- personal_access_token
- oauth2
required:
- id
- name
- scopes
- authentication
platform_ad_account:
type:
- object
- 'null'
properties:
id:
type: integer
external_id:
type: string
name:
type: string
platform:
type: string
currency:
type:
- string
- 'null'
timezone:
type:
- string
- 'null'
workspace:
type: object
properties:
id:
type: integer
name:
type: string
required:
- id
- name
required:
- id
- external_id
- name
- platform
- currency
- timezone
- workspace
next_steps:
type: array
description: Present only when meta_connected is false.
items:
type: string
required:
- meta_connected
- agent
- platform_ad_account
'400':
description: Malformed URL encoding.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
'401':
description: Missing, invalid, expired or revoked token, inactive binding, insufficient agent permission, or a management API key.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/AgentContextAuthError'
- $ref: '#/components/schemas/ErrorMessage'
headers:
WWW-Authenticate:
description: Bearer error and protected resource metadata.
schema:
type: string
'403':
description: The accessible workspace scope or operation is unauthorized, or an ambiguous workspace selection was omitted.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/AgentContextAuthError'
- $ref: '#/components/schemas/ErrorMessage'
'404':
description: Workspace is nonexistent, inaccessible or noncanonical.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRouteNotFound'
'422':
description: Invalid account ID, mismatched account binding, or ambiguous active accounts.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'429':
description: The shared API rate limit is exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
headers:
Retry-After:
description: Seconds until a retry is allowed.
schema:
type: integer
security:
- agentContextKey: []
- agentContextOAuth:
- mcp:use
components:
schemas:
ValidationError:
type: object
properties:
message:
type: string
errors:
type: object
additionalProperties:
type: array
items:
type: string
required:
- message
- errors
title: ValidationError
ErrorMessage:
type: object
properties:
message:
type: string
required:
- message
title: ErrorMessage
AgentContextAuthError:
type: object
properties:
error:
type: string
error_description:
type: string
required:
- error
- error_description
title: AgentContextAuthError
ApiRouteNotFound:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- api_route_not_found
message:
type: string
resolution:
type: string
required:
- code
- message
- resolution
request:
type: object
properties:
method:
type: string
path:
type: string
required:
- method
- path
resources:
type: object
properties:
documentation:
type: string
openapi:
type: string
required:
- documentation
- openapi
required:
- error
- request
- resources
title: ApiRouteNotFound
securitySchemes:
workspaceSecret:
type: http
description: Per-workspace Server secret. It authenticates only the Signals workspace represented by the credential.
scheme: bearer
sandboxCredential:
type: http
description: Short-lived Sandbox key issued by POST /sandbox/keys.
scheme: bearer
workspaceActionKey:
type: http
description: Workspace key with read-actions for reads or propose-actions for writes. Optional positive account ID. A bound key may name only its own account; a different ID returns 422. An unbound key requires exactly one active available advertising account with an active connection; omission uses that account and a supplied ID must match it. Multiple active accounts return 422 even when account_id is supplied.
scheme: bearer
planWriter:
type: http
description: An OAuth agent or account-bound Workspace Key with write access and the plan-create grant.
scheme: bearer
workspaceInventoryKey:
type: http
description: Workspace read key with the get_inventory_metrics grant. Account-bound keys can read only their bound account.
scheme: bearer
planReader:
type: http
description: An OAuth agent or account-bound Workspace Key with read access to the approved ad account.
scheme: bearer
ruleReader:
type: http
description: 'A workspace-scoped key with read ability and actions.rules.index or actions.rules.show access to the bound account. Send Accept: application/json.'
scheme: bearer
ruleWriter:
type: http
description: 'A workspace-scoped key with write ability and the actions.rules.store or actions.rules.update grant. Send Accept: application/json.'
scheme: bearer
agentContextKey:
type: http
description: Workspace key with read ability, ad-account.read permission and the agent.context grant.
scheme: bearer
agentContextOAuth:
type: oauth2
description: OAuth access token for an active approved agent principal with mcp:use, ad-account.read and agent.context authorization. Authorization code with PKCE and device authorization tokens are accepted. This scheme applies only to agent context.
flows:
authorizationCode:
authorizationUrl: https://plainrouter.com/oauth2/authorize
tokenUrl: https://plainrouter.com/oauth2/token
refreshUrl: https://plainrouter.com/oauth2/token
scopes:
mcp:use: Use the approved agent principal.
creativeWriter:
type: http
description: Workspace-bound write credential with a grant authorizing creative intake.
scheme: bearer
testReader:
type: http
description: A workspace principal with read tier and the launch.plans.index and launch.plans.show grants for this account.
scheme: bearer
testWriter:
type: http
description: A workspace principal with write tier and the launch.plans.store grant for this account.
scheme: bearer
x-action-types:
- increase_budget
- decrease_budget
- pause
- resume
- replace_creative
- shift_spend
- rollback
- create_campaign
- create_ad_set
- create_ad
- upload_asset
x-signed: true