cURL

# Set a unique key once per new action; persist it and reuse it for every retry.
: "${REFLECTIONS_KEY:?Set REFLECTIONS_KEY before running this example}"
: "${REFLECTIONS_CREATE_LICENSE_DRAFT_IDEMPOTENCY_KEY:?Set REFLECTIONS_CREATE_LICENSE_DRAFT_IDEMPOTENCY_KEY before running this example}"

curl --fail-with-body --max-time 30 -X POST 'https://app.reflections.ai/v1/license_drafts' \
  -H "Authorization: Bearer $REFLECTIONS_KEY" \
  -H "Reflections-Version: 2026-10-15" \
  -H "Idempotency-Key: $REFLECTIONS_CREATE_LICENSE_DRAFT_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
  "kind": "renew",
  "license": "lic_k5zba2q8v1m3n7p4r6s9t0wxyh",
  "scope": {
    "window": {
      "starts_at": "2027-04-01T00:00:00-04:00",
      "ends_at": "2027-09-30T00:00:00-04:00",
      "time_zone": "America/New_York"
    }
  },
  "signer": "talent",
  "note": "Spring and summer 2027, on the same terms."
}'

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

// Set a unique key once per new action; persist it and reuse it for every retry.
const apiKey = env.REFLECTIONS_KEY;
if (!apiKey) throw new Error("Set REFLECTIONS_KEY before running this example");
const idempotencyKey = env.REFLECTIONS_CREATE_LICENSE_DRAFT_IDEMPOTENCY_KEY;
if (!idempotencyKey) throw new Error("Set REFLECTIONS_CREATE_LICENSE_DRAFT_IDEMPOTENCY_KEY before running this example");

const response = await fetch("https://app.reflections.ai/v1/license_drafts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Reflections-Version": "2026-10-15",
    "Idempotency-Key": idempotencyKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
    "kind": "renew",
    "license": "lic_k5zba2q8v1m3n7p4r6s9t0wxyh",
    "scope": {
      "window": {
        "starts_at": "2027-04-01T00:00:00-04:00",
        "ends_at": "2027-09-30T00:00:00-04:00",
        "time_zone": "America/New_York"
      }
    },
    "signer": "talent",
    "note": "Spring and summer 2027, on the same terms."
  }),
  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 json
import os
from urllib.error import HTTPError
from urllib.request import Request, urlopen

# Set a unique key once per new action; persist it and reuse it for every retry.
apiKey = os.environ["REFLECTIONS_KEY"]
if not apiKey:
    raise ValueError("Set REFLECTIONS_KEY before running this example")
idempotencyKey = os.environ["REFLECTIONS_CREATE_LICENSE_DRAFT_IDEMPOTENCY_KEY"]
if not idempotencyKey:
    raise ValueError("Set REFLECTIONS_CREATE_LICENSE_DRAFT_IDEMPOTENCY_KEY before running this example")

headers = {
    "Authorization": f"Bearer {apiKey}",
    "Reflections-Version": "2026-10-15",
    "Idempotency-Key": idempotencyKey,
    "Content-Type": "application/json",
}
data = json.dumps({
    "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
    "kind": "renew",
    "license": "lic_k5zba2q8v1m3n7p4r6s9t0wxyh",
    "scope": {
        "window": {
            "starts_at": "2027-04-01T00:00:00-04:00",
            "ends_at": "2027-09-30T00:00:00-04:00",
            "time_zone": "America/New_York",
        },
    },
    "signer": "talent",
    "note": "Spring and summer 2027, on the same terms.",
}).encode("utf-8")
request = Request("https://app.reflections.ai/v1/license_drafts",
                  method="POST", headers=headers, data=data)
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"
    "strings"
    "time"
)

func main() {
    // Set a unique key once per new action; persist it and reuse it for every retry.
    apiKey := os.Getenv("REFLECTIONS_KEY")
    if apiKey == "" {
        panic("Set REFLECTIONS_KEY before running this example")
    }
    idempotencyKey := os.Getenv("REFLECTIONS_CREATE_LICENSE_DRAFT_IDEMPOTENCY_KEY")
    if idempotencyKey == "" {
        panic("Set REFLECTIONS_CREATE_LICENSE_DRAFT_IDEMPOTENCY_KEY before running this example")
    }

    body := strings.NewReader(`{
      "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
      "kind": "renew",
      "license": "lic_k5zba2q8v1m3n7p4r6s9t0wxyh",
      "scope": {
        "window": {
          "starts_at": "2027-04-01T00:00:00-04:00",
          "ends_at": "2027-09-30T00:00:00-04:00",
          "time_zone": "America/New_York"
        }
      },
      "signer": "talent",
      "note": "Spring and summer 2027, on the same terms."
    }`)
    request, err := http.NewRequest("POST", "https://app.reflections.ai/v1/license_drafts", body)
    if err != nil {
        panic(err)
    }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    request.Header.Set("Reflections-Version", "2026-10-15")
    request.Header.Set("Idempotency-Key", idempotencyKey)
    request.Header.Set("Content-Type", "application/json")
    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))
}

{
  "id": "ldr_hz4ngq81vhagynxm3ds9q2acz4",
  "object": "license_draft",
  "livemode": true,
  "status": "open",
  "kind": "renew",
  "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
  "licensee": "acct_2q8v1m3n7p4r6s9t0wxyhk5zba",
  "license": "lic_k5zba2q8v1m3n7p4r6s9t0wxyh",
  "license_request": null,
  "scope": {
    "facets": [
      "fct_5zba2q8v1m3n7p4r6s9t0wxyhk"
    ],
    "modalities": [
      "image"
    ],
    "kinds": [
      "depiction"
    ],
    "purposes": [
      "advertising"
    ],
    "commercial": true,
    "channels": [
      "social",
      "web"
    ],
    "territories": [
      "US",
      "CA"
    ],
    "window": {
      "starts_at": "2027-04-01T00:00:00-04:00",
      "ends_at": "2027-09-30T00: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"
    }
  },
  "terms_digest": "sha256:d499df2ff47603a092c7a59be9e329a344e6c23590c1ddfdbe6fc5a0ea32274b",
  "signer": "talent",
  "signing_url": "https://app.reflections.ai/sign/ldr_hz4ngq81vhagynxm3ds9q2acz4",
  "signed_as_drafted": null,
  "license_revision": null,
  "decision_note": null,
  "note": "Spring and summer 2027, on the same terms.",
  "created_by": "acct_6m8n0p2q4r6s8t0v2w4x6y8z0b",
  "expires_at": "2026-11-16T09:00:00Z",
  "signed_at": null,
  "declined_at": null,
  "metadata": {},
  "created_at": "2026-10-17T09:00:00Z"
}

{
  "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/mandate_required",
  "title": "No mandate with the needed power",
  "status": 403,
  "code": "mandate_required",
  "detail": "Your mandate for tal_9t0wxyhk5zba2q8v1m3n7p4r6s does not include review_outputs.",
  "request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}

{
  "type": "https://docs.reflections.ai/errors/resource_not_found",
  "title": "No such object",
  "status": 404,
  "code": "resource_not_found",
  "request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}

{
  "type": "https://docs.reflections.ai/errors/idempotency_key_in_use",
  "title": "A request with this key is still running",
  "status": 409,
  "code": "idempotency_key_in_use",
  "detail": "Retry with the same key after a short wait.",
  "request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}

{
  "type": "https://docs.reflections.ai/errors/idempotency_key_reused",
  "title": "This key was used for a different request",
  "status": 422,
  "code": "idempotency_key_reused",
  "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>"
}

License drafts

Draft a license

Planned contract — unavailable in test and live modes. This operation is a protocol reference, not a callable endpoint. Start with the working sandbox quickstart.

Prepares terms for the talent’s side to sign: a new license, an answer to a license request, or an amendment or renewal of an existing license. Needs a mandate with issue_licenses for the talent.

A draft grants nothing. A person signs it with a passkey at signing_url, in the Talent Portal: the talent, or a person at your account when signer is representative. The signer may change terms before signing. Signing creates the license or its new revision, and the licensee then accepts it on its hosted acceptance page. No endpoint signs or accepts a license.

Restricted keys need license_drafts:write.

POST

license_drafts

cURL

# Set a unique key once per new action; persist it and reuse it for every retry.
: "${REFLECTIONS_KEY:?Set REFLECTIONS_KEY before running this example}"
: "${REFLECTIONS_CREATE_LICENSE_DRAFT_IDEMPOTENCY_KEY:?Set REFLECTIONS_CREATE_LICENSE_DRAFT_IDEMPOTENCY_KEY before running this example}"

curl --fail-with-body --max-time 30 -X POST 'https://app.reflections.ai/v1/license_drafts' \
  -H "Authorization: Bearer $REFLECTIONS_KEY" \
  -H "Reflections-Version: 2026-10-15" \
  -H "Idempotency-Key: $REFLECTIONS_CREATE_LICENSE_DRAFT_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
  "kind": "renew",
  "license": "lic_k5zba2q8v1m3n7p4r6s9t0wxyh",
  "scope": {
    "window": {
      "starts_at": "2027-04-01T00:00:00-04:00",
      "ends_at": "2027-09-30T00:00:00-04:00",
      "time_zone": "America/New_York"
    }
  },
  "signer": "talent",
  "note": "Spring and summer 2027, on the same terms."
}'

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

// Set a unique key once per new action; persist it and reuse it for every retry.
const apiKey = env.REFLECTIONS_KEY;
if (!apiKey) throw new Error("Set REFLECTIONS_KEY before running this example");
const idempotencyKey = env.REFLECTIONS_CREATE_LICENSE_DRAFT_IDEMPOTENCY_KEY;
if (!idempotencyKey) throw new Error("Set REFLECTIONS_CREATE_LICENSE_DRAFT_IDEMPOTENCY_KEY before running this example");

const response = await fetch("https://app.reflections.ai/v1/license_drafts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Reflections-Version": "2026-10-15",
    "Idempotency-Key": idempotencyKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
    "kind": "renew",
    "license": "lic_k5zba2q8v1m3n7p4r6s9t0wxyh",
    "scope": {
      "window": {
        "starts_at": "2027-04-01T00:00:00-04:00",
        "ends_at": "2027-09-30T00:00:00-04:00",
        "time_zone": "America/New_York"
      }
    },
    "signer": "talent",
    "note": "Spring and summer 2027, on the same terms."
  }),
  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 json
import os
from urllib.error import HTTPError
from urllib.request import Request, urlopen

# Set a unique key once per new action; persist it and reuse it for every retry.
apiKey = os.environ["REFLECTIONS_KEY"]
if not apiKey:
    raise ValueError("Set REFLECTIONS_KEY before running this example")
idempotencyKey = os.environ["REFLECTIONS_CREATE_LICENSE_DRAFT_IDEMPOTENCY_KEY"]
if not idempotencyKey:
    raise ValueError("Set REFLECTIONS_CREATE_LICENSE_DRAFT_IDEMPOTENCY_KEY before running this example")

headers = {
    "Authorization": f"Bearer {apiKey}",
    "Reflections-Version": "2026-10-15",
    "Idempotency-Key": idempotencyKey,
    "Content-Type": "application/json",
}
data = json.dumps({
    "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
    "kind": "renew",
    "license": "lic_k5zba2q8v1m3n7p4r6s9t0wxyh",
    "scope": {
        "window": {
            "starts_at": "2027-04-01T00:00:00-04:00",
            "ends_at": "2027-09-30T00:00:00-04:00",
            "time_zone": "America/New_York",
        },
    },
    "signer": "talent",
    "note": "Spring and summer 2027, on the same terms.",
}).encode("utf-8")
request = Request("https://app.reflections.ai/v1/license_drafts",
                  method="POST", headers=headers, data=data)
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"
    "strings"
    "time"
)

func main() {
    // Set a unique key once per new action; persist it and reuse it for every retry.
    apiKey := os.Getenv("REFLECTIONS_KEY")
    if apiKey == "" {
        panic("Set REFLECTIONS_KEY before running this example")
    }
    idempotencyKey := os.Getenv("REFLECTIONS_CREATE_LICENSE_DRAFT_IDEMPOTENCY_KEY")
    if idempotencyKey == "" {
        panic("Set REFLECTIONS_CREATE_LICENSE_DRAFT_IDEMPOTENCY_KEY before running this example")
    }

    body := strings.NewReader(`{
      "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
      "kind": "renew",
      "license": "lic_k5zba2q8v1m3n7p4r6s9t0wxyh",
      "scope": {
        "window": {
          "starts_at": "2027-04-01T00:00:00-04:00",
          "ends_at": "2027-09-30T00:00:00-04:00",
          "time_zone": "America/New_York"
        }
      },
      "signer": "talent",
      "note": "Spring and summer 2027, on the same terms."
    }`)
    request, err := http.NewRequest("POST", "https://app.reflections.ai/v1/license_drafts", body)
    if err != nil {
        panic(err)
    }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    request.Header.Set("Reflections-Version", "2026-10-15")
    request.Header.Set("Idempotency-Key", idempotencyKey)
    request.Header.Set("Content-Type", "application/json")
    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))
}

{
  "id": "ldr_hz4ngq81vhagynxm3ds9q2acz4",
  "object": "license_draft",
  "livemode": true,
  "status": "open",
  "kind": "renew",
  "talent": "tal_9t0wxyhk5zba2q8v1m3n7p4r6s",
  "licensee": "acct_2q8v1m3n7p4r6s9t0wxyhk5zba",
  "license": "lic_k5zba2q8v1m3n7p4r6s9t0wxyh",
  "license_request": null,
  "scope": {
    "facets": [
      "fct_5zba2q8v1m3n7p4r6s9t0wxyhk"
    ],
    "modalities": [
      "image"
    ],
    "kinds": [
      "depiction"
    ],
    "purposes": [
      "advertising"
    ],
    "commercial": true,
    "channels": [
      "social",
      "web"
    ],
    "territories": [
      "US",
      "CA"
    ],
    "window": {
      "starts_at": "2027-04-01T00:00:00-04:00",
      "ends_at": "2027-09-30T00: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"
    }
  },
  "terms_digest": "sha256:d499df2ff47603a092c7a59be9e329a344e6c23590c1ddfdbe6fc5a0ea32274b",
  "signer": "talent",
  "signing_url": "https://app.reflections.ai/sign/ldr_hz4ngq81vhagynxm3ds9q2acz4",
  "signed_as_drafted": null,
  "license_revision": null,
  "decision_note": null,
  "note": "Spring and summer 2027, on the same terms.",
  "created_by": "acct_6m8n0p2q4r6s8t0v2w4x6y8z0b",
  "expires_at": "2026-11-16T09:00:00Z",
  "signed_at": null,
  "declined_at": null,
  "metadata": {},
  "created_at": "2026-10-17T09:00:00Z"
}

{
  "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/mandate_required",
  "title": "No mandate with the needed power",
  "status": 403,
  "code": "mandate_required",
  "detail": "Your mandate for tal_9t0wxyhk5zba2q8v1m3n7p4r6s does not include review_outputs.",
  "request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}

{
  "type": "https://docs.reflections.ai/errors/resource_not_found",
  "title": "No such object",
  "status": 404,
  "code": "resource_not_found",
  "request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}

{
  "type": "https://docs.reflections.ai/errors/idempotency_key_in_use",
  "title": "A request with this key is still running",
  "status": 409,
  "code": "idempotency_key_in_use",
  "detail": "Retry with the same key after a short wait.",
  "request_id": "req_8f2k4m6p8r0t2v4x6z8b0d2f4h"
}

{
  "type": "https://docs.reflections.ai/errors/idempotency_key_reused",
  "title": "This key was used for a different request",
  "status": 422,
  "code": "idempotency_key_reused",
  "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"

Idempotency-Key

string

A unique key for this operation, up to 255 characters. In test mode, POST keys are scoped to your account and mode and bind the endpoint and body for 24 hours. A different endpoint or body with the same key is refused.

Initial live check and generation creation require a nonempty key. Each operation has a separate account-scoped namespace; retain the same API key, body and idempotency key for retries within 24 hours of creation. A pending check returns 202 with status: "checking". Completed checks replay their sealed response; successful generation POSTs replay the original accepted 202, so use GET for current state. Live verification is a read-only query that returns a fresh verification ID on each call, without exact response caching.

The broader delegated-account contract also scopes keys to Reflections-Account; delegated requests and the other planned live POST operations remain unsupported.

Maximum string length: 255

Body

application/json

talent

string

required

The talent the license is for. Your mandate for them must include issue_licenses.

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

kind

enum<string>

default:issue

issue: a new license, with licensee and a full scope. change_request: an answer to a request of kind change; set by license_request. amend: new terms for an active or scheduled license. renew: a new window for an active, scheduled or expired license. Set license_request and the kind follows from the request.

Available options:

issue,

change_request,

amend,

renew

license_request

string

The request this draft answers. The request must be sent. When the draft is signed, the request becomes signed.

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

license

string

For amend and renew, the license to change.

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

licensee

string

For issue without a license_request, the account that will hold the license. It must have hold_licenses.

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

scope

object

The terms. For issue without a license_request, the full scope. With a license_request, only the terms that differ from what was asked. For amend and renew, only the terms that change; omitted fields keep the current revision's value.

Show child attributes

signer

enum<string>

default:talent

Who signs. talent: the talent signs in the Talent Portal and is notified now. representative: a person at your account with issue_licenses signs.

Available options:

talent,

representative

note

string

Shown to the licensee on the acceptance page.

Maximum string length: 1000

expires_at

string<date-time>

When the draft can no longer be signed. At most 30 days ahead, and the default.

metadata

object

Keys and values of your own, returned on the draft.

Show child attributes

Response

The draft, open for signature.

string

required

The draft's ID, ldr_….

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

object

string

required

Always license_draft.

Allowed value: "license_draft"

livemode

boolean

required

true in live mode, false in test mode.

status

enum<string>

required

open until the signer signs or declines it, it is discarded, or it passes expires_at.

Available options:

open,

signed,

declined,

discarded,

expired

kind

enum<string>

required

What signing creates. issue: a new license. change_request: a new revision answering a request of kind change. amend: new terms for license. renew: a new window for license.

Available options:

issue,

change_request,

amend,

renew

talent

string

required

The talent the license is for.

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

licensee

string

required

The account that holds or will hold the license. It accepts what is signed on its hosted acceptance page.

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

scope

object

required

The full terms the signer will see, with the current revision's values filled in.

Show child attributes

terms_digest

string

required

The terms_digest the revision will carry if it is signed as drafted. Compare it with the signed revision's to see whether the signer changed anything.

Pattern: ^sha256:[0-9a-f]{64}$

signer

enum<string>

required

Who signs. talent: the talent, in the Talent Portal. representative: a person at your account with issue_licenses.

Available options:

talent,

representative

created_by

string

required

The representative account that prepared the draft.

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

expires_at

string<date-time>

required

When the draft can no longer be signed. 30 days after it was created, unless you set an earlier time.

created_at

string<date-time>

required

When you created the draft.

license

string | null

The license this draft changes, or, once an issue draft is signed, the license it became.

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

license_request

string | null

The license request this draft answers. null when it answers none.

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

signing_url

string<uri> | null

The Talent Portal page where the signer reads and signs the draft with a passkey. Present while open.

signed_as_drafted

boolean | null

Once signed, false when the signer changed terms before signing.

license_revision

string | null

The revision that signing created.

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

decision_note

string | null

The signer's note when they declined.

note

string | null

Shown to the licensee on the acceptance page. null when you sent none.

signed_at

string<date-time> | null

When the signer signed. null unless signed.

declined_at

string<date-time> | null

When the signer declined. null unless declined.

metadata

object

Keys and values of your own.

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

Draft a license

Authorizations

Headers

Body

Response