GogoScreen Account 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 Account API
  version: 1.0.0
servers:
- url: https://api.gogoscreen.com/api/v1
tags:
- description: Who the credential belongs to, and what the account is allowed to do.
  name: Account
paths:
  /account:
    get:
      description: Who this credential acts for, and the account's video-time balance. The fields an integration needs, not the whole account record.
      operationId: account.me
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  account:
                    additionalProperties: false
                    properties:
                      createdAt:
                        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'
                      deletionStatus:
                        anyOf:
                        - type: string
                        - type: 'null'
                      email:
                        type: string
                      emailVerified:
                        description: Read from the credential, which is the authority on verification.
                        type: boolean
                      id:
                        type: string
                      name:
                        anyOf:
                        - type: string
                        - type: 'null'
                      role:
                        anyOf:
                        - type: string
                        - type: 'null'
                    required:
                    - id
                    - email
                    - name
                    - emailVerified
                    - role
                    - createdAt
                    - deletionStatus
                    type: object
                  credential:
                    additionalProperties: false
                    properties:
                      apiKeyId:
                        anyOf:
                        - type: string
                        - type: 'null'
                      kind:
                        enum:
                        - user
                        - api_key
                        type: string
                      scopes:
                        anyOf:
                        - items:
                            type: string
                          type: array
                        - type: 'null'
                        description: null means a user credential, which carries every scope.
                    required:
                    - kind
                    - apiKeyId
                    - scopes
                    type: object
                  wallet:
                    anyOf:
                    - 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
                    - type: 'null'
                    description: null only when the balance could not be read; a status question never fails on the wallet.
                required:
                - account
                - wallet
                - credential
                type: object
          description: The account behind this credential
          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:
        - account:read
      - DashboardSession: []
      summary: The account behind this credential
      tags:
      - Account
      x-actors:
      - user
      - api_key
      x-async-kind: null
      x-audit: null
      x-idempotent: false
      x-kind: read
      x-mcp-tool: account_me
      x-rate-class: read
      x-rate-per-minute: 600
      x-scopes:
      - account: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