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