EveryPage Account API

openapi: 3.2.0
info:
  title: EveryPage Account 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: Account
paths:
  /api/v1:
    get:
      tags:
      - Account
      summary: API discovery document
      operationId: getApiIndex
      description: Zero-credential discovery document at the API root - pointers to this specification, the developer docs, the credential lanes (API keys, OAuth server and protected-resource metadata), the rate-limit convention, the error format and the versioning policy. The one read an agent can make before it has a key.
      security: []
      responses:
        '200':
          description: The discovery document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiIndex'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/v1/user:
    get:
      tags:
      - Account
      summary: Your account and plan
      operationId: getCurrentUser
      description: The caller's profile - `name`, `email`, `subscription` (`free`, `basic`, `pro`), `hasDealLicense`, the free-trial fields (`trialEligible`, `trialEndsAt`, `storageLimited`) and `created_at`. Scope `profile`. `isAdmin` is always false through the API (the internal flag is masked on every token-authenticated read).
      security:
      - bearerAuth: []
      - oauth2:
        - profile
      responses:
        '200':
          description: Account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    ApiIndex:
      type: object
      description: The zero-auth discovery document served at GET /api/v1.
      properties:
        name:
          type: string
          example: EveryPage API
        version:
          type: string
          example: v1
        status:
          type: string
          example: ok
        openapi:
          type: string
          format: uri
        documentation:
          type: string
          format: uri
        authentication:
          type: object
          properties:
            type:
              type: string
              example: bearer
            api_keys:
              type: string
              format: uri
              description: Where to create a self-serve API key.
            oauth_metadata:
              type: string
              format: uri
              description: RFC 8414 authorization-server metadata.
            resource_metadata:
              type: string
              format: uri
              description: RFC 9728 protected-resource metadata for /api/v1.
            scopes:
              type: array
              items:
                type: string
        rate_limit:
          type: object
          properties:
            requests_per_minute:
              type: integer
              example: 120
            headers:
              type: array
              items:
                type: string
        errors:
          type: string
          example: application/problem+json
        versioning:
          type: string
          format: uri
        free_plan:
          type: object
          properties:
            signup:
              type: string
              format: uri
            card_required:
              type: boolean
              example: false
            sandbox:
              type: boolean
              example: false
              description: There is no separate sandbox; use a free account.
    User:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        subscription:
          type: string
          enum:
          - free
          - basic
          - pro
        isAdmin:
          type: boolean
          description: 'Always false through the API: the internal admin flag is masked on every token-authenticated read, so third-party apps never see it.'
        created_at:
          type: string
          format: date-time
        hasDealLicense:
          type: boolean
          description: True for lifetime-deal holders with an active deal license (their entitlement comes from the license rather than a subscription).
        trialEligible:
          type: boolean
          description: True when the account can still start its one free trial of a paid plan.
        trialEndsAt:
          type: string
          format: date-time
          description: Present while the account is on a free trial it has not yet paid for; when the trial ends.
        storageLimited:
          type: boolean
          description: True during an unpaid free trial - upload size and active-file limits stay at the free plan's until the plan starts.
    Problem:
      type: object
      description: 'RFC 9457 Problem Details, returned with `Content-Type: application/problem+json` for every error under /api/v1 and for unknown /api paths. Branch on `code` (or `status`), never on `detail`. `type` links to the matching section of https://everypage.co/docs/developers/authentication#error-responses.'
      required:
      - type
      - title
      - status
      - detail
      - code
      properties:
        type:
          type: string
          format: uri
          example: https://everypage.co/docs/developers/authentication#insufficient-scope
        title:
          type: string
          description: The HTTP reason phrase.
          example: Forbidden
        status:
          type: integer
          minimum: 400
          maximum: 599
          example: 403
        detail:
          type: string
          description: The human-readable message for this occurrence.
          example: 'insufficient_scope: requires files:write'
        instance:
          type: string
          format: uri
          description: Absolute URL of the request that failed.
          example: https://everypage.co/api/v1/files
        code:
          type: string
          description: Stable machine code. Values not listed here are the HTTP reason phrase in lower snake case and may be added without notice.
          enum:
          - missing_token
          - invalid_token
          - insufficient_scope
          - plan_required
          - validation_error
          - forbidden
          - not_found
          - method_not_allowed
          - conflict
          - gone
          - payload_too_large
          - unsupported_media_type
          - unprocessable
          - rate_limited
          - internal_error
          - service_unavailable
        hint:
          type: string
          description: What to do next.
          example: Reconnect with a token that grants files:write. API keys (ep_live_) hold every scope.
  responses:
    Unauthorized:
      description: No or invalid API key, OAuth token, manage token or claim token (code `missing_token` or `invalid_token`).
      headers:
        WWW-Authenticate:
          description: RFC 6750 challenge, e.g. `Bearer realm="EveryPage API", error="invalid_token"`.
          schema:
            type: string
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    RateLimited:
      description: Over the limit - 120 requests per minute per Authorization value on /api/v1 (webhook test 10/min; the Canva lane 30/min per IP). Code `rate_limited`; wait for `Retry-After`.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  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