GogoScreen Usage API

openapi: 3.2.0
info:
  contact:
    email: support@gogoscreen.com
    name: GogoScreen support
    url: https://gogoscreen.com/support
  description: 'Every operation is defined once, and this document and the MCP tool list are both built from that one definition, so they cannot disagree.


    **Authentication.** `Authorization: Bearer gsk_…` (an API key) or `X-API-Key: gsk_…`. A dashboard session token in the same Bearer header is accepted so the dashboard''s developer console can call this API with the session it already has.


    **Pagination.** Cursor only. Pass `limit` (1–100, default 20) and the previous page''s `nextCursor`; a null `nextCursor` is the end of the walk. Cursors are opaque — do not build one.


    **Errors.** Every non-2xx answers `{ error: { code, message, details?, requestId } }`. Branch on `code`; quote `requestId` when reporting a failure.


    **Rate limits.** Every answer carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds). Each operation belongs to a class — read 600/min, write 120/min, expensive 20/min, charge 20/min — counted per credential, and a key may carry a lower per-minute or per-day limit of its own. Above those there is one ceiling per ACCOUNT, shared by every key and every class, so holding more keys does not raise what an account can do. A refusal is `429 rate_limited` with `Retry-After` and `details.scope` naming which ceiling it was: `minute`, `day` or `account`.


    **Long work.** Renders, storyboards, scans, generations and exports are jobs: they answer a resource with a `state` of queued/running/succeeded/failed/cancelled and a `pollAfterMs`. Poll until the state is terminal, or subscribe to a webhook.


    **Idempotency.** Every mutating operation takes an `Idempotency-Key` header; a replay with the same body returns the stored response.


    **Webhooks.** Register an endpoint with `POST /webhooks` and you are told when work finishes instead of polling for it. The secret is returned once, at registration.


    Every delivery is a `POST` of a `WebhookEvent` with these headers: `Gogoscreen-Event-Id`, `Gogoscreen-Event-Type`, `Gogoscreen-Delivery-Id`, `Gogoscreen-Delivery-Attempt` and `Gogoscreen-Signature`.


    The signature is `t=,v1=`, where the hex is `HMAC-SHA256(secret, "." + rawBody)`. **Verify it against the RAW body you received**, not against a re-serialised object — key order and whitespace are not guaranteed to survive a parse. Reject a `t` more than 300 seconds from your own clock, and compare the hex in constant time.


    Delivery is **at-least-once**: six attempts on an exponential backoff, a redirect is refused rather than followed, and only a 2xx within 10 seconds counts as delivered. Dedupe on `Gogoscreen-Event-Id`, and treat a repeat as the same event. After 20 consecutive failed deliveries an endpoint is disabled and has to be turned back on.


    The webhooks guide at https://gogoscreen.com/docs/webhooks has a short verifier example.'
  license:
    name: GogoScreen API Terms
    url: https://gogoscreen.com/terms
  summary: Make product walkthroughs and marketing videos from a URL.
  title: GogoScreen Usage API
  version: 1.0.0
servers:
- url: https://api.gogoscreen.com/api/v1
tags:
- description: What this account has called, and how much of it.
  name: Usage
paths:
  /usage:
    get:
      description: Public API calls over a window, by day and by operation, plus the video time the account spent in the same window. A key sees only its own calls; a signed-in person sees the whole account. Windows are inclusive of `from` and exclusive of `to`, default the last 30 days, and may span at most 92.
      operationId: usage.get
      parameters:
      - description: The start of the window, inclusive. Defaults to 30 days ago.
        in: query
        name: from
        required: false
        schema:
          format: date-time
          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
          type: string
      - description: The end of the window, exclusive. Defaults to now.
        in: query
        name: to
        required: false
        schema:
          format: date-time
          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
          type: string
      - description: Which breakdowns to compute. `both` is the default.
        in: query
        name: groupBy
        required: false
        schema:
          default: both
          enum:
          - day
          - operation
          - both
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  byDay:
                    description: UTC days, ascending. Absent days are absent, not zero.
                    items:
                      additionalProperties: false
                      properties:
                        day:
                          type: string
                        errors:
                          type: number
                        requests:
                          type: number
                      required:
                      - day
                      - requests
                      - errors
                      type: object
                    type: array
                  byOperation:
                    description: Busiest first.
                    items:
                      additionalProperties: false
                      properties:
                        errors:
                          type: number
                        operation:
                          type: string
                        requests:
                          type: number
                      required:
                      - operation
                      - requests
                      - errors
                      type: object
                    type: array
                  details:
                    anyOf:
                    - additionalProperties: false
                      properties:
                        note:
                          type: string
                      required:
                      - note
                      type: object
                    - type: 'null'
                    description: Present only when a field above could not be answered, saying which and why.
                  from:
                    format: date-time
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                    type: string
                  requests:
                    description: Every public call in the window, whatever it answered.
                    type: number
                  scope:
                    description: '`api_key` when a key asked — it sees only its own calls.'
                    enum:
                    - api_key
                    - account
                    type: string
                  secondsCharged:
                    anyOf:
                    - type: number
                    - type: 'null'
                    description: 'Video time charged in the window, from the wallet ledger — the only authority on spend. For a signed-in person this is the ACCOUNT''s total. For a KEY it is the total of the work THAT KEY created: renders and marketing exports it started, joined to the ledger by the row they were charged against. Work started in the dashboard is not a key''s, and one key never sees another''s.'
                  to:
                    format: date-time
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                    type: string
                required:
                - from
                - to
                - scope
                - requests
                - byDay
                - byOperation
                - secondsCharged
                - details
                type: object
          description: What this credential has been doing
          headers:
            Cache-Control:
              description: Always `private, no-store`.
              schema:
                type: string
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: '`validation_failed` — That request is not valid.'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: '`unauthorized` — Authentication is required.'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: '`forbidden_scope` — This credential does not carry the scope this operation needs.'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: '`not_found` — No such resource.'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: '`rate_limited` — Too many requests. Try again shortly.'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: '`internal_error` — Something went wrong. Try again.'
      security:
      - ApiKey:
        - usage:read
      - DashboardSession: []
      summary: What this credential has been doing
      tags:
      - Usage
      x-actors:
      - user
      - api_key
      x-async-kind: null
      x-audit: null
      x-idempotent: false
      x-kind: read
      x-mcp-tool: usage_get
      x-rate-class: read
      x-rate-per-minute: 600
      x-scopes:
      - usage:read
components:
  schemas:
    Error:
      additionalProperties: false
      properties:
        error:
          additionalProperties: false
          properties:
            code:
              description: The machine-readable refusal. Branch on this.
              enum:
              - abuse_check_unavailable
              - account_blocked
              - account_deleted
              - account_pending_deletion
              - ai_rate_limited
              - already_settled
              - anon_lifetime_cap
              - assistant_conversation_full
              - assistant_daily_limit
              - assistant_unavailable
              - avatar_unavailable
              - avatar_unknown
              - background_unknown
              - body_invalid
              - brand_kit_required
              - brand_logo_not_retained
              - brand_logo_source_mismatch
              - budget_exhausted
              - campaign_copy_overflow
              - campaign_logo_aspect_unsupported
              - campaign_speed_breaks_music_ending
              - campaign_speed_breaks_narration_fit
              - campaign_speed_not_offered
              - campaign_unsupported_claim
              - campaign_visuals_insufficient
              - caption_style_unknown
              - capture_incompatible
              - capture_unknown
              - conflict
              - conversation_closed
              - conversation_not_found
              - credentials_required
              - description_invalid
              - edit_not_understood
              - email_unverified
              - expected_revision_required
              - expired
              - export_in_flight
              - feature_disabled
              - forbidden_scope
              - gallery_example
              - generation_busy
              - generation_idempotency_conflict
              - generation_not_found
              - generation_not_retryable
              - gone
              - handoff_failed
              - handoff_limit
              - hint_improve_failed
              - hint_required
              - hint_too_long
              - idempotency_conflict
              - idempotency_in_progress
              - idempotency_key_required
              - idempotency_key_unscoped
              - insufficient_seconds
              - internal_error
              - invalid_brand_kit
              - invalid_campaign_narration
              - invalid_cover_text
              - invalid_cursor
              - invalid_revision
              - language_unknown
              - length_below_minimum
              - login_origins_invalid
              - login_url_invalid
              - login_url_required
              - missing_required_footage
              - name_invalid
              - no_beats
              - no_revision
              - not_finished
              - not_found
              - not_ready
              - options_invalid
              - orientation_unknown
              - origin_daily_cap
              - paid_account_required
              - payload_too_large
              - preview_failed
              - project_not_found
              - queue_unavailable
              - rate_limited
              - reservation_failed
              - revision_configuration_mismatch
              - revision_conflict
              - service_unavailable
              - settings_invalid
              - site_not_allowed
              - source_deleted
              - source_expired
              - source_export_in_flight
              - source_idempotency_conflict
              - source_inspection_busy
              - source_inspection_stopping
              - source_kind_mismatch
              - source_not_found
              - source_not_ready
              - source_owner_not_found
              - source_owner_unavailable
              - source_refresh_url_mismatch
              - source_render_not_found
              - source_unreadable
              - source_version_expired
              - source_version_mismatch
              - source_version_not_found
              - storage_unavailable
              - storyboard_empty
              - storyboard_expired
              - storyboard_in_flight
              - template_limit
              - template_not_found
              - template_unknown
              - too_many_endpoints
              - too_many_in_flight
              - tts_unavailable
              - unauthorized
              - unknown_beat
              - unknown_template
              - unsupported_audio_mode
              - unsupported_duration
              - unsupported_export
              - unsupported_format
              - unsupported_media_type
              - url_bare_host
              - url_blocked
              - url_credentials
              - url_dns
              - url_invalid
              - url_malformed
              - url_missing
              - url_no_host
              - url_private
              - url_scheme
              - validation_failed
              - vault_unavailable
              - verification_required
              - voice_language
              - voice_unknown
              - wallet_unavailable
              - webhook_endpoint_disabled
              - webhook_host_denied
              - webhook_url_blocked
              - webhook_url_invalid
              - website_demo_invalid
              type: string
            details:
              additionalProperties: true
              description: 'The structured half: the fields that failed, the seconds needed, the statuses offered. A refusal you can act on may also carry `missing`: one entry per thing to put right, each `{ field, section, message }`, where `section` is the part of the editor that owns the field (story, style, sound or export) and `message` is the sentence a person is shown for it. It is the same list the dashboard draws beside its Export button.'
              type: object
            message:
              description: A sentence written for a person. Never contains what you sent.
              type: string
            requestId:
              description: Quote this when reporting a failure.
              type:
              - string
              - 'null'
          required:
          - code
          - message
          - requestId
          type: object
      required:
      - error
      type: object
  securitySchemes:
    ApiKey:
      bearerFormat: gsk_…
      description: An API key, created in the dashboard's developer console. Also accepted as `X-API-Key`.
      scheme: bearer
      type: http
    DashboardSession:
      bearerFormat: JWT
      description: A dashboard session token, the credential the dashboard itself holds.
      scheme: bearer
      type: http
x-rate-classes:
  charge:
    perMinute: 20
  expensive:
    perMinute: 20
  read:
    perMinute: 600
  write:
    perMinute: 120
x-scopes:
- catalog:read
- account:read
- wallet:read
- usage:read
- storyboards:read
- storyboards:write
- renders:read
- renders:write
- marketing:read
- marketing:write
- marketing:export
- webhooks:manage
- keys:manage
- assistant:use