openapi: 3.2.0
info:
  title: Plainrouter Cookie Declaration API
  version: 0.5.0
  description: 'Operations tagged CookieDeclaration across 2 of this provider''s published API definitions: dev-plainrouter-openapi.json, plainrouter-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://plainrouter.com/api/v1
  description: Production
security:
- workspaceSecret: []
tags:
- name: CookieDeclaration
paths:
  /cookie-declarations/{publishableKey}:
    get:
      operationId: getCookieDeclaration
      description: Public on every plan. Returns latest completed scan metadata, never values. Invalid keys return 404 before the 300/minute per-key limiter.
      summary: Read the public cookie declaration
      tags:
      - CookieDeclaration
      parameters:
      - name: publishableKey
        in: path
        required: true
        description: Workspace publishable key from the customer page source; pk_live_ followed by 32 alphanumeric characters.
        schema:
          type: string
          pattern: ^pk_live_[A-Za-z0-9]{32}$
      responses:
        '200':
          description: Latest completed scan metadata, or empty groups if none has completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CookieDeclaration'
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
                enum:
                - '*'
            Cache-Control:
              schema:
                type: string
              example: max-age=60, public
        '404':
          description: Unknown well-formed key returns an empty array. Invalid-format keys return the API route-not-found response before any limiter bucket is created.
          content:
            application/json:
              schema:
                anyOf:
                - type: array
                  items:
                    type: string
                  maxItems: 0
                - $ref: '#/components/schemas/ApiRouteNotFound'
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
                enum:
                - '*'
        '429':
          description: The 300-per-minute allowance for this key is exhausted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
                enum:
                - '*'
            Cache-Control:
              schema:
                type: string
                const: no-store, private
            Retry-After:
              schema:
                type: integer
      security: []
    servers:
    - url: https://plainrouter.com/api/v1
      description: Production
components:
  schemas:
    CookieDeclarationItem:
      type: object
      properties:
        name:
          type: string
        provider_domain:
          type: string
        party:
          type: string
          enum:
          - first
          - third
        expiry:
          type: string
          description: Observed UTC expiry date, Session, or Until removed.
        purpose:
          type:
          - string
          - 'null'
          description: Purpose from the Open Cookie Database, where available.
      required:
      - name
      - provider_domain
      - party
      - expiry
      - purpose
      title: CookieDeclarationItem
    ErrorMessage:
      type: object
      properties:
        message:
          type: string
      required:
      - message
      title: ErrorMessage
    CookieDeclaration:
      type: object
      properties:
        scan_date:
          type:
          - string
          - 'null'
          format: date-time
          description: Date of the latest completed scan; null when no scan has completed. Blocked and failed scans do not replace it.
        categories:
          type: object
          properties:
            necessary:
              type: object
              properties:
                cookies:
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieDeclarationItem'
                storage_keys:
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieDeclarationItem'
              required:
              - cookies
              - storage_keys
            functional:
              type: object
              properties:
                cookies:
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieDeclarationItem'
                storage_keys:
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieDeclarationItem'
              required:
              - cookies
              - storage_keys
            analytics:
              type: object
              properties:
                cookies:
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieDeclarationItem'
                storage_keys:
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieDeclarationItem'
              required:
              - cookies
              - storage_keys
            marketing:
              type: object
              properties:
                cookies:
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieDeclarationItem'
                storage_keys:
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieDeclarationItem'
              required:
              - cookies
              - storage_keys
            unclassified:
              type: object
              properties:
                cookies:
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieDeclarationItem'
                storage_keys:
                  type: array
                  items:
                    $ref: '#/components/schemas/CookieDeclarationItem'
              required:
              - cookies
              - storage_keys
          required:
          - necessary
          - functional
          - analytics
          - marketing
          - unclassified
      required:
      - scan_date
      - categories
      title: CookieDeclaration
    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. Unbound keys select an available advertising account with account_id.
      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
    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
    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.
x-refined-from:
- dev-plainrouter-openapi.json
- plainrouter-openapi.json
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