placementapi-com Meta API

openapi: 3.2.0
info:
  title: Placement Meta API
  version: 1.0.0
  description: 'Normalised backlink placement inventory, deduplicated across multiple suppliers, with independent verification, held quotes, ordering, content handling and post-placement outcome tracking. Every price is the buyer price in credits (1 credit = 1 US cent), already normalised from supplier currencies, so the figure you plan with is the figure you are charged. Supplier identity is never exposed.


    Authenticate with a `pk_live_…` API key as a Bearer token. Keys carry scopes: `read` (catalogue, quotes, account reads) and `order` (anything that moves money). An MCP server exposing the same operations as tools is available at https://api.placementapi.com/mcp with the same Bearer key; the tools call these endpoints, so pricing and verification are identical either way. Unknown query parameters and brief fields are refused with 400 rather than ignored.'
  contact:
    email: hello@placementapi.com
  termsOfService: https://placementapi.com/terms
servers:
- url: https://api.placementapi.com
security:
- apiKey: []
tags:
- name: Meta
  description: Service banner, health and field semantics.
paths:
  /v1:
    get:
      tags:
      - Meta
      operationId: service_banner
      security: []
      summary: Service banner
      description: Unauthenticated. Confirms the service is up and points at the authenticated endpoints and the MCP transport. Carries no inventory or pricing.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  service:
                    type: string
                  version:
                    type: string
                  docs:
                    type: string
                  schema:
                    type: string
                  mcp:
                    type: object
                  endpoints:
                    type: array
                    items:
                      type: string
  /v1/health:
    get:
      tags:
      - Meta
      operationId: health
      summary: Catalogue coverage and freshness
      description: 'Check this before trusting prices. Customers see coverage counts and how many integrated suppliers'' latest snapshot is stale, with the supplier roster itself withheld. `stale_after_hours` is the snapshot-recency threshold behind `suppliers_stale` and `all_fresh` — scrape recency for coverage, not the price judgement. Whether a specific price is current is measured per supplier: each catalogue price is labelled fresh, aged or stale against that supplier''s own derived drift window, and an aged price is still quoted and orderable at its observed date (see /v1/offers and quote lines), so price freshness is a measured, per-supplier judgement rather than one fixed cutoff.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  configured:
                    type: boolean
                  stale_after_hours:
                    type: integer
                    description: Snapshot age at which a supplier counts stale for `suppliers_stale` / `all_fresh`. Coverage recency only; each price's own fresh/aged/stale label is decided per supplier, not by this value.
                  all_fresh:
                    type: boolean
                    description: True when at least one supplier is integrated and none counts stale.
                  coverage:
                    type: object
                    properties:
                      suppliers_integrated:
                        type: integer
                      suppliers_stale:
                        type: integer
                      total_offers:
                        type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/schema:
    get:
      tags:
      - Meta
      operationId: field_semantics
      summary: Field semantics for agents
      description: Hand-authored, machine-readable description of what the fields MEAN (inventory modes, verification, pricing, anchor distribution, rate limits), for a model-driven client to self-configure against. Not a type schema; this document is.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                  description:
                    type: string
                  critical_semantics:
                    type: object
                  mcp:
                    type: object
                  endpoints:
                    type: object
                  placement_types:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Machine-readable code, snake_case.
        detail:
          description: Human-readable explanation, or a zod flatten() object on validation failures.
      additionalProperties: true
  responses:
    Unauthorized:
      description: 'Missing, malformed or revoked Bearer credential: `{ error: "unauthorized" }`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'Customer API key (`pk_live_…`) in `Authorization: Bearer <key>`. Issue from POST /v1/keys or the dashboard. Endpoints marked session-only reject API keys.'