Plainrouter Draft Batch File Import API

openapi: 3.2.0
info:
  title: Plainrouter Conversion Draft Batch File Import API
  version: 0.5.0
  description: Plainrouter public Signals Conversion API.
servers:
- url: https://plainrouter.com/api/v1
  description: Production
security:
- workspaceSecret: []
tags:
- name: DraftBatchFileImport
paths:
  /mcp/launcher/import:
    post:
      operationId: launcher.file-import
      description: Import a CSV or spreadsheet into a governed Launcher draft batch for the workspace and account authorized by the execution key.
      summary: Import a Launcher draft batch
      tags:
      - DraftBatchFileImport
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DraftBatchFileImportRequest'
      responses:
        '403':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    const: insufficient_scope
                  error_description:
                    type: string
                    const: File import requires at least the workspace write execution tier.
                required:
                - error
                - error_description
        '401':
          description: Invalid or missing Server secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: A missing, inaccessible or non-canonical workspace selector returns the api_route_not_found envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiRouteNotFound'
        '200':
          description: Draft batch result and syntactic row failures.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
        '422':
          description: Integer selector or file validation returns message plus field errors. Rejected import files return error, reason_code and syntactic_row_failures.
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - type: object
                  properties:
                    error:
                      type: string
                      enum:
                      - file_import_rejected
                    reason_code:
                      type: string
                    syntactic_row_failures:
                      type: array
                      items:
                        type: object
                        properties:
                          import_row_number:
                            type: integer
                          reason_code:
                            type: string
                        required:
                        - import_row_number
                        - reason_code
                  required:
                  - error
                  - reason_code
                  - syntactic_row_failures
      servers:
      - url: https://plainrouter.com
components:
  schemas:
    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
    DraftBatchFileImportRequest:
      type: object
      properties:
        file:
          type: string
          format: binary
          contentMediaType: application/octet-stream
        source_adset_id:
          type: string
          pattern: ^[0-9]+$
        source_ad_id:
          type: string
          pattern: ^[0-9]+$
        mode:
          $ref: '#/components/schemas/DraftBatchMode'
        folder_to_adset:
          type: boolean
        grouping_enabled:
          type: boolean
        account_id:
          type: integer
          minimum: 1
        workspace_id:
          type: integer
          minimum: 1
      required:
      - file
      - source_adset_id
      - source_ad_id
      - mode
      title: DraftBatchFileImportRequest
    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
    DraftBatchMode:
      type: string
      enum:
      - duplicate_adset
      - duplicate_adset_per_media
      - add_to_adset
      title: DraftBatchMode
  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