cURL

: "${REFLECTIONS_KEY:?Set REFLECTIONS_KEY before running this example}"

curl --fail-with-body --max-time 30 'https://app.reflections.ai/v1/licenses?limit=10' \
  -H "Authorization: Bearer $REFLECTIONS_KEY" \
  -H "Reflections-Version: 2026-10-15"

import { env, exit } from "node:process";

const apiKey = env.REFLECTIONS_KEY;
if (!apiKey) throw new Error("Set REFLECTIONS_KEY before running this example");

const response = await fetch("https://app.reflections.ai/v1/licenses?limit=10", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Reflections-Version": "2026-10-15",
  },
  signal: AbortSignal.timeout(30_000),
});
const responseBody = await response.text();
if (!response.ok) {
  console.error(`HTTP ${response.status}: ${responseBody}`);
  exit(1);
}
console.log(responseBody);

import os
from urllib.error import HTTPError
from urllib.request import Request, urlopen

apiKey = os.environ["REFLECTIONS_KEY"]
if not apiKey:
    raise ValueError("Set REFLECTIONS_KEY before running this example")

headers = {
    "Authorization": f"Bearer {apiKey}",
    "Reflections-Version": "2026-10-15",
}
request = Request("https://app.reflections.ai/v1/licenses?limit=10",
                  method="GET", headers=headers)
try:
    with urlopen(request, timeout=30) as response:
        print(response.read().decode("utf-8"))
except HTTPError as error:
    error_body = error.read().decode("utf-8")
    raise RuntimeError(f"HTTP {error.code}: {error_body}") from error

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
    "time"
)

func main() {
    apiKey := os.Getenv("REFLECTIONS_KEY")
    if apiKey == "" {
        panic("Set REFLECTIONS_KEY before running this example")
    }

    request, err := http.NewRequest("GET", "https://app.reflections.ai/v1/licenses?limit=10", nil)
    if err != nil {
        panic(err)
    }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    request.Header.Set("Reflections-Version", "2026-10-15")
    client := &http.Client{Timeout: 30 * time.Second}
    response, err := client.Do(request)
    if err != nil {
        panic(err)
    }
    defer response.Body.Close()
    responseBody, err := io.ReadAll(response.Body)
    if err != nil {
        panic(err)
    }
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        panic(fmt.Sprintf("HTTP %d: %s", response.StatusCode, responseBody))
    }
    fmt.Print(string(responseBody))
}

{
  "object": "list",
  "data": [
    {
      "id": "lic_k5zba2q8v1m3n7p4r6s9t0wxyh",
      "object": "license",
      "livemode": true,
      "status": "active",
      "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
      "licensee": "acct_2q8v1m3n7p4r6s9t0wxyhk5zba",
      "issued_by": {
        "party": "talent",
        "account": null
      },
      "handle": "K7Q4M2",
      "current_revision": "lrv_p4r6s9t0wxyhk5zba2q8v1m3n7",
      "revision_number": 1,
      "pending_revision": null,
      "terms_digest": "sha256:39f18c8bef02b5226b9feaa92e526ed30b81b91650d8a10b503281b169f44431",
      "scope": {
        "facets": [
          "fct_5zba2q8v1m3n7p4r6s9t0wxyhk"
        ],
        "modalities": [
          "image"
        ],
        "kinds": [
          "depiction"
        ],
        "purposes": [
          "advertising"
        ],
        "commercial": true,
        "channels": [
          "social",
          "web"
        ],
        "territories": [
          "US",
          "CA"
        ],
        "window": {
          "starts_at": "2026-10-01T00:00:00-04:00",
          "ends_at": "2027-03-31T00:00:00-04:00",
          "time_zone": "America/New_York"
        },
        "adjustments": {
          "reframe": true,
          "background_extension": true,
          "lighting": true,
          "text_overlay": true,
          "body_and_age": false,
          "expression": false,
          "hair": false,
          "pose": false,
          "wardrobe": true,
          "objects": true,
          "skin_retouch": false,
          "endorsement": false
        },
        "prohibited_changes": [
          "body_and_age",
          "expression",
          "hair",
          "pose",
          "skin_retouch",
          "endorsement"
        ],
        "required_attributes": [
          "identity.samePerson",
          "appearance.bodyAndAge",
          "appearance.expression",
          "appearance.hair",
          "appearance.pose",
          "appearance.skinRetouch",
          "context.endorsement"
        ],
        "rules": {
          "never": [
            "Do not show alcohol or tobacco."
          ],
          "always": [],
          "brief": null
        },
        "release_policy": "per_output_review",
        "escalation_window": "P7D",
        "final_deliverables": 24,
        "sessions": {
          "permitted": false
        },
        "material_access": [],
        "platforms": {
          "mode": "any_connected",
          "accounts": []
        },
        "sublicense": "none",
        "training": "prohibited",
        "disclosure": "brand",
        "attribution": null,
        "post_revocation": {
          "policy": "retain"
        },
        "exclusivity": {
          "exclusive": false,
          "category": null
        },
        "conflicts": [],
        "compensation": {
          "type": "per_unit",
          "per_unit": {
            "units": "placements",
            "rate": {
              "amount": 25000,
              "currency": "usd"
            },
            "per": 1
          },
          "minimum": {
            "amount": 500000,
            "currency": "usd"
          },
          "schedule": "monthly"
        }
      },
      "acceptance_url": null,
      "accepted_at": "2026-09-28T16:02:00Z",
      "suspended_at": null,
      "revoked_at": null,
      "declined_at": null,
      "metadata": {},
      "created_at": "2026-09-27T11:15:00Z"
    },
    {
      "id": "lic_ba2q8v1m3n7p4r6s9t0wxyhk5z",
      "object": "license",
      "livemode": true,
      "status": "active",
      "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
      "licensee": "acct_7p4r6s9t0wxyhk5zba2q8v1m3n",
      "issued_by": {
        "party": "talent",
        "account": null
      },
      "handle": "V6R2T9",
      "current_revision": "lrv_7p4r6s9t0wxyhk5zba2q8v1m3n",
      "revision_number": 1,
      "pending_revision": null,
      "scope": {
        "facets": [
          "fct_v1m3n7p4r6s9t0wxyhk5zba2q8"
        ],
        "modalities": [
          "speech"
        ],
        "kinds": [
          "impersonation"
        ],
        "purposes": [
          "personal",
          "branded_content"
        ],
        "commercial": true,
        "channels": [
          "in_app",
          "audio",
          "web"
        ],
        "territories": [
          "US"
        ],
        "window": {
          "starts_at": "2026-09-02T00:00:00Z",
          "ends_at": "2027-06-30T23:59:59Z",
          "time_zone": null
        },
        "required_attributes": [
          "identity.samePerson"
        ],
        "release_policy": "after_checks",
        "escalation_window": "P7D",
        "final_deliverables": null,
        "monthly_limits": {
          "seconds": 100000
        },
        "sessions": {
          "permitted": true,
          "sampling": {
            "audio_window_max": "PT15S",
            "transcript": "every_turn"
          }
        },
        "material_access": [],
        "platforms": {
          "mode": "listed",
          "accounts": [
            "acct_7p4r6s9t0wxyhk5zba2q8v1m3n"
          ]
        },
        "sublicense": "end_users_personal",
        "training": "prohibited",
        "disclosure": "licensed",
        "attribution": null,
        "post_revocation": {
          "policy": "retain"
        },
        "exclusivity": null,
        "conflicts": [],
        "compensation": {
          "type": "per_unit",
          "per_unit": {
            "units": "seconds",
            "rate": {
              "amount": 2,
              "currency": "usd"
            },
            "per": 1
          },
          "schedule": "monthly"
        }
      },
      "acceptance_url": null,
      "accepted_at": "2026-09-01T16:45:00Z",
      "suspended_at": null,
      "revoked_at": null,
      "declined_at": null,
      "metadata": {},
      "created_at": "2026-09-01T10:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

{
  "type": "https://docs.reflections.ai/errors/parameter_invalid",
  "title": "A parameter is invalid",
  "status": 400,
  "code": "parameter_invalid",
  "param": "use.territories[1]",
  "detail": "\"UK\" is not an ISO 3166-1 alpha-2 code. Use \"GB\".",
  "request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}

{
  "type": "https://docs.reflections.ai/errors/invalid_api_key",
  "title": "The API key is not valid",
  "status": 401,
  "code": "invalid_api_key",
  "request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}

{
  "type": "https://docs.reflections.ai/errors/account_not_connected",
  "title": "The licensee has not connected your platform",
  "status": 403,
  "code": "account_not_connected",
  "detail": "acct_2q8v1m3n7p4r6s9t0wxyhk5zba has no active connection with your account.",
  "request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}

{
  "type": "https://docs.reflections.ai/errors/rate_limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "invalid_request",
  "request_id": "<string>",
  "detail": "<string>",
  "param": "<string>",
  "doc_url": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "invalid_request",
  "request_id": "<string>",
  "detail": "<string>",
  "param": "<string>",
  "doc_url": "<string>"
}

Licenses

List licenses

Test mode available. Live mode available for this read. Test keys return fictional fixtures. A live key reads the licenses whose sole licensee is the calling account, or with role=issuer, the licenses the calling account issued as talent. In test mode, role=issuer returns an empty list. Delegated connections and representative access are planned.

Live results include the current signed revision’s terms_digest and a partial scope: window, required_attributes, release_policy and final_deliverables, plus external_creation only when that grant is explicitly signed. Omitted fields grant nothing. Signed channel and territory labels are not mapped to protocol enums. No private reference IDs or source media are returned, and live revision retrieval is not available. See Live license reads.

Restricted keys need licenses:read.

GET

licenses

cURL

: "${REFLECTIONS_KEY:?Set REFLECTIONS_KEY before running this example}"

curl --fail-with-body --max-time 30 'https://app.reflections.ai/v1/licenses?limit=10' \
  -H "Authorization: Bearer $REFLECTIONS_KEY" \
  -H "Reflections-Version: 2026-10-15"

import { env, exit } from "node:process";

const apiKey = env.REFLECTIONS_KEY;
if (!apiKey) throw new Error("Set REFLECTIONS_KEY before running this example");

const response = await fetch("https://app.reflections.ai/v1/licenses?limit=10", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Reflections-Version": "2026-10-15",
  },
  signal: AbortSignal.timeout(30_000),
});
const responseBody = await response.text();
if (!response.ok) {
  console.error(`HTTP ${response.status}: ${responseBody}`);
  exit(1);
}
console.log(responseBody);

import os
from urllib.error import HTTPError
from urllib.request import Request, urlopen

apiKey = os.environ["REFLECTIONS_KEY"]
if not apiKey:
    raise ValueError("Set REFLECTIONS_KEY before running this example")

headers = {
    "Authorization": f"Bearer {apiKey}",
    "Reflections-Version": "2026-10-15",
}
request = Request("https://app.reflections.ai/v1/licenses?limit=10",
                  method="GET", headers=headers)
try:
    with urlopen(request, timeout=30) as response:
        print(response.read().decode("utf-8"))
except HTTPError as error:
    error_body = error.read().decode("utf-8")
    raise RuntimeError(f"HTTP {error.code}: {error_body}") from error

package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
    "time"
)

func main() {
    apiKey := os.Getenv("REFLECTIONS_KEY")
    if apiKey == "" {
        panic("Set REFLECTIONS_KEY before running this example")
    }

    request, err := http.NewRequest("GET", "https://app.reflections.ai/v1/licenses?limit=10", nil)
    if err != nil {
        panic(err)
    }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    request.Header.Set("Reflections-Version", "2026-10-15")
    client := &http.Client{Timeout: 30 * time.Second}
    response, err := client.Do(request)
    if err != nil {
        panic(err)
    }
    defer response.Body.Close()
    responseBody, err := io.ReadAll(response.Body)
    if err != nil {
        panic(err)
    }
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        panic(fmt.Sprintf("HTTP %d: %s", response.StatusCode, responseBody))
    }
    fmt.Print(string(responseBody))
}

{
  "object": "list",
  "data": [
    {
      "id": "lic_k5zba2q8v1m3n7p4r6s9t0wxyh",
      "object": "license",
      "livemode": true,
      "status": "active",
      "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
      "licensee": "acct_2q8v1m3n7p4r6s9t0wxyhk5zba",
      "issued_by": {
        "party": "talent",
        "account": null
      },
      "handle": "K7Q4M2",
      "current_revision": "lrv_p4r6s9t0wxyhk5zba2q8v1m3n7",
      "revision_number": 1,
      "pending_revision": null,
      "terms_digest": "sha256:39f18c8bef02b5226b9feaa92e526ed30b81b91650d8a10b503281b169f44431",
      "scope": {
        "facets": [
          "fct_5zba2q8v1m3n7p4r6s9t0wxyhk"
        ],
        "modalities": [
          "image"
        ],
        "kinds": [
          "depiction"
        ],
        "purposes": [
          "advertising"
        ],
        "commercial": true,
        "channels": [
          "social",
          "web"
        ],
        "territories": [
          "US",
          "CA"
        ],
        "window": {
          "starts_at": "2026-10-01T00:00:00-04:00",
          "ends_at": "2027-03-31T00:00:00-04:00",
          "time_zone": "America/New_York"
        },
        "adjustments": {
          "reframe": true,
          "background_extension": true,
          "lighting": true,
          "text_overlay": true,
          "body_and_age": false,
          "expression": false,
          "hair": false,
          "pose": false,
          "wardrobe": true,
          "objects": true,
          "skin_retouch": false,
          "endorsement": false
        },
        "prohibited_changes": [
          "body_and_age",
          "expression",
          "hair",
          "pose",
          "skin_retouch",
          "endorsement"
        ],
        "required_attributes": [
          "identity.samePerson",
          "appearance.bodyAndAge",
          "appearance.expression",
          "appearance.hair",
          "appearance.pose",
          "appearance.skinRetouch",
          "context.endorsement"
        ],
        "rules": {
          "never": [
            "Do not show alcohol or tobacco."
          ],
          "always": [],
          "brief": null
        },
        "release_policy": "per_output_review",
        "escalation_window": "P7D",
        "final_deliverables": 24,
        "sessions": {
          "permitted": false
        },
        "material_access": [],
        "platforms": {
          "mode": "any_connected",
          "accounts": []
        },
        "sublicense": "none",
        "training": "prohibited",
        "disclosure": "brand",
        "attribution": null,
        "post_revocation": {
          "policy": "retain"
        },
        "exclusivity": {
          "exclusive": false,
          "category": null
        },
        "conflicts": [],
        "compensation": {
          "type": "per_unit",
          "per_unit": {
            "units": "placements",
            "rate": {
              "amount": 25000,
              "currency": "usd"
            },
            "per": 1
          },
          "minimum": {
            "amount": 500000,
            "currency": "usd"
          },
          "schedule": "monthly"
        }
      },
      "acceptance_url": null,
      "accepted_at": "2026-09-28T16:02:00Z",
      "suspended_at": null,
      "revoked_at": null,
      "declined_at": null,
      "metadata": {},
      "created_at": "2026-09-27T11:15:00Z"
    },
    {
      "id": "lic_ba2q8v1m3n7p4r6s9t0wxyhk5z",
      "object": "license",
      "livemode": true,
      "status": "active",
      "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
      "licensee": "acct_7p4r6s9t0wxyhk5zba2q8v1m3n",
      "issued_by": {
        "party": "talent",
        "account": null
      },
      "handle": "V6R2T9",
      "current_revision": "lrv_7p4r6s9t0wxyhk5zba2q8v1m3n",
      "revision_number": 1,
      "pending_revision": null,
      "scope": {
        "facets": [
          "fct_v1m3n7p4r6s9t0wxyhk5zba2q8"
        ],
        "modalities": [
          "speech"
        ],
        "kinds": [
          "impersonation"
        ],
        "purposes": [
          "personal",
          "branded_content"
        ],
        "commercial": true,
        "channels": [
          "in_app",
          "audio",
          "web"
        ],
        "territories": [
          "US"
        ],
        "window": {
          "starts_at": "2026-09-02T00:00:00Z",
          "ends_at": "2027-06-30T23:59:59Z",
          "time_zone": null
        },
        "required_attributes": [
          "identity.samePerson"
        ],
        "release_policy": "after_checks",
        "escalation_window": "P7D",
        "final_deliverables": null,
        "monthly_limits": {
          "seconds": 100000
        },
        "sessions": {
          "permitted": true,
          "sampling": {
            "audio_window_max": "PT15S",
            "transcript": "every_turn"
          }
        },
        "material_access": [],
        "platforms": {
          "mode": "listed",
          "accounts": [
            "acct_7p4r6s9t0wxyhk5zba2q8v1m3n"
          ]
        },
        "sublicense": "end_users_personal",
        "training": "prohibited",
        "disclosure": "licensed",
        "attribution": null,
        "post_revocation": {
          "policy": "retain"
        },
        "exclusivity": null,
        "conflicts": [],
        "compensation": {
          "type": "per_unit",
          "per_unit": {
            "units": "seconds",
            "rate": {
              "amount": 2,
              "currency": "usd"
            },
            "per": 1
          },
          "schedule": "monthly"
        }
      },
      "acceptance_url": null,
      "accepted_at": "2026-09-01T16:45:00Z",
      "suspended_at": null,
      "revoked_at": null,
      "declined_at": null,
      "metadata": {},
      "created_at": "2026-09-01T10:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

{
  "type": "https://docs.reflections.ai/errors/parameter_invalid",
  "title": "A parameter is invalid",
  "status": 400,
  "code": "parameter_invalid",
  "param": "use.territories[1]",
  "detail": "\"UK\" is not an ISO 3166-1 alpha-2 code. Use \"GB\".",
  "request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}

{
  "type": "https://docs.reflections.ai/errors/invalid_api_key",
  "title": "The API key is not valid",
  "status": 401,
  "code": "invalid_api_key",
  "request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}

{
  "type": "https://docs.reflections.ai/errors/account_not_connected",
  "title": "The licensee has not connected your platform",
  "status": 403,
  "code": "account_not_connected",
  "detail": "acct_2q8v1m3n7p4r6s9t0wxyhk5zba has no active connection with your account.",
  "request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}

{
  "type": "https://docs.reflections.ai/errors/rate_limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "invalid_request",
  "request_id": "<string>",
  "detail": "<string>",
  "param": "<string>",
  "doc_url": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "code": "invalid_request",
  "request_id": "<string>",
  "detail": "<string>",
  "param": "<string>",
  "doc_url": "<string>"
}

Authorizations

Authorization

string

header

required

Your secret key, rk_test_… or rk_live_…, sent as Authorization: Bearer <key>. Keep it on your server. Restricted keys carry only the scopes you give them.

Headers

Reflections-Version

string

The dated API version. Defaults to the version your account is pinned to.

Example:

"2026-10-15"

Reflections-Account

string

Act for a connected licensee. The value is the licensee's account ID. Requires an active connection between that account and yours.

Pattern: ^acct_[0-9a-hjkmnp-tv-z]{26}$

Query Parameters

role

enum<string>

default:licensee

licensee (the default): licenses you hold. issuer: licenses you issued as talent.

Available options:

licensee,

issuer

talent

string

Only licenses granted by this talent.

Pattern: ^tal_[0-9a-hjkmnp-tv-z]{26}$

status

enum<string>

Only licenses with this status, such as active. Live reads also accept void; the sandbox status filter does not. pending_acceptance: signed on the talent's side, waiting for the licensee. scheduled: accepted, window not started. active: in force. suspended: paused by the talent or a representative. expired: the window ended. declined: the licensee declined it. revoked: ended by the talent or a representative. void: voided in the issuing system; the license grants no use. The test-mode status filter does not accept void.

Available options:

pending_acceptance,

scheduled,

active,

suspended,

expired,

declined,

revoked,

void

limit

integer

default:20

Number of objects to return, 1 to 100.

Required range: 1 <= x <= 100

cursor

string

The next_cursor from the previous page.

Response

A page of licenses.

object

string

required

Always list.

Allowed value: "list"

has_more

boolean

required

Whether another page exists.

next_cursor

string | null

Pass as cursor to read the next page.

data

object[]

The licenses on this page, newest first.

Show child attributes

Overview

Account

Talent

Facets

Resolutions

Licenses

License requests

Connections

Files

Checks

Generations

Sessions

Receipts

Verifications

Revocations

Usage records

Statements

Mandates

Escalations

License drafts

Webhook endpoints

Events

Discovery

OAuth

Test helpers

Webhooks

Real-time

Formats

MCP

List licenses

Authorizations

Headers

Query Parameters

Response