GogoScreen Wallet 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 Wallet API
  version: 1.0.0
servers:
- url: https://api.gogoscreen.com/api/v1
tags:
- description: 'The account''s seconds: the balance, and every movement of it.'
  name: Wallet
paths:
  /wallet:
    get:
      description: 'How many seconds of finished video this account can still make, by bucket: a plan''s seconds for the current billing month (which end with the period), top up seconds (which never expire), free seconds, and what is currently held by work in flight. `availableSeconds` is the one number a reservation is judged against.'
      operationId: wallet.get
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  wallet:
                    additionalProperties: false
                    properties:
                      availableSeconds:
                        description: What a new render or export may be reserved against, right now.
                        type: number
                      freeSeconds:
                        type: number
                      paygSeconds:
                        type: number
                      planActive:
                        type: boolean
                      planExpiresAt:
                        anyOf:
                        - 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
                        - type: 'null'
                      planId:
                        anyOf:
                        - type: string
                        - type: 'null'
                      planSeconds:
                        type: number
                      reservedSeconds:
                        type: number
                    required:
                    - planSeconds
                    - planId
                    - planExpiresAt
                    - planActive
                    - paygSeconds
                    - freeSeconds
                    - reservedSeconds
                    - availableSeconds
                    type: object
                required:
                - wallet
                type: object
          description: The video-time balance
          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:
        - wallet:read
      - DashboardSession: []
      summary: The video-time balance
      tags:
      - Wallet
      x-actors:
      - user
      - api_key
      x-async-kind: null
      x-audit: null
      x-idempotent: false
      x-kind: read
      x-mcp-tool: wallet_get
      x-rate-class: read
      x-rate-per-minute: 600
      x-scopes:
      - wallet:read
  /wallet/ledger:
    get:
      description: 'Every movement of this account''s seconds, newest first: grants, reservations, charges and releases, each with the row it was for. Joined to a render or an export by `refType` + `refId`; the ledger is the record of what was spent, and no other count of seconds is authoritative.'
      operationId: wallet.ledger.list
      parameters:
      - description: How many rows to return (1–100).
        in: query
        name: limit
        required: false
        schema:
          default: 20
          maximum: 100
          minimum: 1
          type: integer
      - description: 'The `nextCursor` of the previous page. Opaque: do not build one.'
        in: query
        name: cursor
        required: false
        schema:
          maxLength: 512
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  data:
                    items:
                      additionalProperties: false
                      properties:
                        balanceAfter:
                          anyOf:
                          - additionalProperties: {}
                            propertyNames:
                              type: string
                            type: object
                          - type: 'null'
                          description: The whole wallet as it stood after this row, so a statement reads down the page without re-summing.
                        bucket:
                          anyOf:
                          - type: string
                          - type: 'null'
                        createdAt:
                          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
                        id:
                          anyOf:
                          - type: string
                          - type: number
                        kind:
                          description: 'What happened: a grant, a reservation, a charge, a release, an expiry.'
                          type: string
                        note:
                          anyOf:
                          - type: string
                          - type: 'null'
                        refId:
                          anyOf:
                          - type: string
                          - type: 'null'
                        refType:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: What the row is about — `render`, `marketing_export` — and `refId` is that row's id.
                        seconds:
                          description: 'Signed: negative took time away.'
                          type: number
                      required:
                      - kind
                      - seconds
                      - bucket
                      - refType
                      - refId
                      - note
                      - balanceAfter
                      - createdAt
                      - id
                      type: object
                    type: array
                  nextCursor:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: Pass as `cursor` for the next page; null on the last page.
                required:
                - data
                - nextCursor
                type: object
          description: Where the video time went
          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. · `invalid_cursor` — That page cursor 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:
        - wallet:read
      - DashboardSession: []
      summary: Where the video time went
      tags:
      - Wallet
      x-actors:
      - user
      - api_key
      x-async-kind: null
      x-audit: null
      x-idempotent: false
      x-kind: read
      x-mcp-tool: wallet_ledger_list
      x-rate-class: read
      x-rate-per-minute: 600
      x-scopes:
      - wallet: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