EveryPage Embedding API

openapi: 3.2.0
info:
  title: EveryPage Embedding API
  description: 'Upload documents and get trackable share links programmatically. Authenticate with a personal API key (create one at https://everypage.co/account under API keys) or an OAuth 2.0 access token, sent as a bearer token. Every error under /api/v1 is an RFC 9457 problem document (application/problem+json) - branch on its `code`.


    Versioning: /api/v1 is the contract - changes inside a version are additive only, and anything scheduled to go away carries Deprecation (RFC 9745) and Sunset (RFC 8594) headers with at least six months'' notice (https://everypage.co/docs/developers/versioning; no active deprecations). Rate limits: 120 requests per minute per bearer token, advertised on every response in RateLimit and RateLimit-Policy (IETF structured fields) plus X-RateLimit-*, with Retry-After on 429. OAuth 2.0 server metadata: https://everypage.co/.well-known/oauth-authorization-server.'
  version: 1.1.0
  termsOfService: https://everypage.co/terms
  x-deprecation-policy:
    url: https://everypage.co/docs/developers/versioning
    minimumNoticeDays: 180
    signals:
    - Deprecation
    - Sunset
    - Link rel=deprecation
    activeDeprecations: []
  contact:
    email: support@everypage.co
servers:
- url: https://everypage.co
security:
- bearerAuth: []
tags:
- name: Embedding
paths:
  /oembed:
    get:
      tags:
      - Embedding
      summary: oEmbed provider endpoint
      operationId: getOEmbed
      description: Turn a pasted EveryPage share link into an embeddable rich object (an iframe on the /embed/ path). Public and unauthenticated; rate-limited per IP (60/min). Accepts any share-link form - UUID, short id, or a vanity slug on the owner's custom domain - and the /embed/ form. Dead links of every kind (unknown, expired, view limit reached, unclaimed) answer a uniform 404.
      security: []
      parameters:
      - name: url
        in: query
        required: true
        schema:
          type: string
          format: uri
        description: The full share link to resolve (URL-encoded).
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - json
        description: Only json is supported; other values answer 501.
      responses:
        '200':
          description: oEmbed rich payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OEmbed'
        '400':
          description: Missing or non-absolute `url` parameter.
          content:
            text/plain:
              schema:
                type: string
        '404':
          description: The link does not resolve to a viewable document (unknown, expired, burned or unclaimed).
          content:
            text/plain:
              schema:
                type: string
        '429':
          $ref: '#/components/responses/RateLimitedPublic'
        '501':
          description: A `format` other than json was requested.
          content:
            text/plain:
              schema:
                type: string
components:
  responses:
    RateLimitedPublic:
      description: Per-IP rate limit exceeded on a public endpoint (60 requests per minute). Plain-text body; wait for `Retry-After`.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        text/plain:
          schema:
            type: string
  schemas:
    OEmbed:
      type: object
      description: Standard oEmbed 1.0 rich-type response.
      properties:
        version:
          type: string
          example: '1.0'
        type:
          type: string
          example: rich
        provider_name:
          type: string
          example: EveryPage
        provider_url:
          type: string
          example: https://everypage.co
        title:
          type: string
          example: proposal.pdf
        html:
          type: string
          description: An <iframe> on the durable /embed/ path (short id or UUID - never the renameable slug).
        width:
          type: integer
          example: 800
        height:
          type: integer
          example: 600
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'An API key (ep_live_...) or OAuth access token (ep_at_...) sent as `Authorization: Bearer <token>`. API keys hold every scope; OAuth tokens are limited to the scopes granted at consent.'
    oauth2:
      type: oauth2
      description: Authorization Code + PKCE (S256 only, no plain). Client authentication on the token and revoke endpoints via HTTP Basic or `client_id`/`client_secret` body params; public clients send `client_id` alone. Refresh tokens rotate on every refresh (the previous one is retired; reusing it revokes the token family) and may be down-scoped with `scope`. Each operation lists the scope it requires.
      flows:
        authorizationCode:
          authorizationUrl: https://everypage.co/oauth/authorize
          tokenUrl: https://everypage.co/oauth/token
          refreshUrl: https://everypage.co/oauth/token
          scopes:
            files:read: See your files and share links
            files:write: Upload, configure, and delete files
            readership:read: See who read your documents
            webhooks:manage: Create, list, test, and delete webhook subscriptions
            profile: See your account email and plan
    manageToken:
      type: http
      scheme: bearer
      bearerFormat: EveryPage manage token
      description: 'The `manageToken` returned by an anonymous upload or a Canva import, sent as `Authorization: Bearer <manageToken>`. Bound to one file; valid for 30 days and only while that file remains unclaimed - once the file is claimed into an account, token calls answer 404. Token callers act at the free tier: plan-gated settings answer 403 and content replacement (Pro) is always refused. Accepted ONLY by PUT /api/v1/files/{uuid}/settings and POST /api/v1/files/{uuid}/content; every other operation answers 401 to it. Not the `claimToken` (a different credential that attaches the file to an account).'
    canvaJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: A Canva Apps SDK user token (`auth.getCanvaUserToken()`), verified against Canva JWKS. Accepted only by the /api/v1/canva/* operations, which are called by the EveryPage Canva app; it is not an EveryPage credential and no other operation accepts it.
externalDocs:
  url: https://everypage.co/developers
  description: Developer guide