Skip to content
OmniscapeRenders API
All pages
  1. Overview
  2. Quick start
  3. Authentication
  4. API reference
    1. GET /media
    2. POST /media
    3. GET /media/{id}/preview
    4. GET /integrations/google/connect
    5. GET /integrations/google
    6. DELETE /integrations/google
    7. GET /integrations/google/folders
    8. POST /media/import
    9. GET /media/imports/{id}
    10. POST /renders
    11. GET /renders/{id}
    12. GET /renders/{id}/download
    13. GET /usage
  5. Code examples
  6. Error handling
  7. Rate limits & quotas
  8. Troubleshooting
  9. Changelog

Reference

Authentication

Every request carries your key as a bearer token against https://omniscape.io. There is no other scheme, no cookie, and no unauthenticated endpoint.

Authorization: Bearer sk_live_…

Keep the key server-side. It is shown once when it is minted and cannot be retrieved afterwards; if it leaks, revoke it in Settings → API and mint another. A revoked key is 401 api_key_revoked immediately, not at the end of some cache window.

Scopes

Keys are default-deny: a call is permitted only when its exact scope is on the key. There are no wildcards and nothing is implied. Mint a key with the least it needs — a key that can only read renders cannot start one, and so cannot spend.

ScopeGrants
media:readGET /api/v1/media, GET /api/v1/media/{id}/preview
media:writePOST /api/v1/media — upload a photo to your library
renders:createPOST /api/v1/renders — the only scope that can spend
renders:readGET /api/v1/renders/{id}, GET /api/v1/renders/{id}/download, GET /api/v1/usage

Scopes are fixed when the key is minted. Adding one means minting a new key, which is deliberate — it makes a widening of privilege a visible event rather than an edit.

Request ids

Every response — success or failure — carries an X-Request-Id header, and error bodies repeat it as request_id:

X-Request-Id: 0f1c8f6a-3b21-4d0e-9a77-2c1f5e8b44d9

Log it. It is the one thing that lets us trace a specific call for you — the detail of what actually went wrong stays on our side, and that id is how we find it.

What a failed auth looks like

Deliberately uninformative. An unknown key and a wrong secret return the same 401 invalid_api_key, so the API cannot be used to test whether a key exists. For the same reason a render or a photo that is not yours is 404, never 403: a 403 would confirm the object is real.

The full list is on Error handling.