> ## Documentation Index
> Fetch the complete documentation index at: https://plainrouter.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get agent context

> Read the authenticated agent and authorized account. With no active account, returns null and connection next steps.



## OpenAPI

````yaml https://plainrouter.com/openapi.json get /agent/context
openapi: 3.1.0
info:
  title: Plainrouter Conversion API
  version: 0.5.0
  description: Plainrouter public Signals Conversion API.
servers:
  - url: https://plainrouter.com/api/v1
    description: Production
security:
  - workspaceSecret: []
paths:
  /agent/context:
    get:
      tags:
        - AgentContext
      summary: Get agent context
      description: >-
        Read the authenticated agent and authorized account. With no active
        account, returns null and connection next steps.
      operationId: agent.context
      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:
            minimum: 1
            type: integer
        - name: workspace_id
          in: query
          description: >-
            Optional workspace grant selector. Required for credentials with
            multiple workspace grants; it must identify an authorized workspace.
          schema:
            minimum: 1
            type: integer
      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: >-
            Workspace selector, grant or operation is unauthorized; malformed or
            missing workspace selection can fail authorization before
            validation.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/AgentContextAuthError'
                  - $ref: '#/components/schemas/ErrorMessage'
        '422':
          description: >-
            Empty workspace_id, 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:
    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
    ValidationError:
      type: object
      properties:
        message:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
      required:
        - message
        - errors
      title: ValidationError
  securitySchemes:
    workspaceSecret:
      type: http
      description: >-
        Per-workspace Server secret. It authenticates only the Signals workspace
        represented by the credential.
      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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.