For AI Agents

Stockfilm Agent API Onboarding

This page is the implementation guide for developers and autonomous agents integrating with Stockfilm licensing workflows.

Catalog SearchRights VerificationQuote + Payment IntentLightning + Solana RailsLicense Execution

Start Here in 60 Seconds

Run this once to test signed authentication end-to-end with a real API call. It creates a valid HMAC signature and posts a search request.

Set your key and secret.
Keep the JSON body exactly the same between signing and send.
Use unix seconds for X-Timestamp.
Send headers: auth, timestamp, signature, and idempotency key.

API_BASE="https://api.stockfilm.com"
API_KEY="replace_with_api_key"
API_SECRET="replace_with_api_secret"
TS="$(date +%s)"
PATH_REQ="/v1/search/assets"
BODY='{"query":"1960s california family","limit":3}'
IDEMPOTENCY_KEY="qs-${TS}"

SIGN_INPUT="${TS}.POST.${PATH_REQ}.${BODY}"
SIG="$(printf "%s" "${SIGN_INPUT}" | openssl dgst -sha256 -hmac "${API_SECRET}" -binary | xxd -p -c 256)"

curl -sS "${API_BASE}${PATH_REQ}" \
  -X POST \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "X-Timestamp: ${TS}" \
  -H "X-Signature: ${SIG}" \
  -H "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  --data "${BODY}"

Tip: append | jq . if you want pretty JSON output in terminal.

1. Discovery URLs

Point agents to these URLs first, then generate requests directly from the OpenAPI spec.

Full guide (human-readable): https://stockfilm.com/for-ai-agents
Compact index for LLM retrieval: https://stockfilm.com/llms.txt
Machine discovery manifest: https://api.stockfilm.com/.well-known/stockfilm-agent.json
Capabilities map: https://api.stockfilm.com/v1/capabilities
OpenAPI contract: https://api.stockfilm.com/openapi.json

2. Authentication and Signing

Read-only requests can use API key auth only. Mutating requests (POST/PUT/PATCH/DELETE) must include HMAC signature headers.

Auth headers: Authorization: Bearer <api_key> or X-API-Key
Required write headers: X-Timestamp, X-Signature, Idempotency-Key
String to sign: {timestamp}.{METHOD}.{path}.{raw_json_body}

Use unix timestamp seconds and an HMAC-SHA256 signature with your API secret. Keep request JSON stable between signing and send.

3. Core Transaction Flow

Search: POST /v1/search/assets with query and filters.
Rights verify: POST /v1/rights/verify for intended usage scope.
Quote: POST /v1/quotes choose rail: lightning_btc, solana_sol, or solana_usdc.
Payment intent: POST /v1/payment-intents to create settlement instructions.
License execute: POST /v1/licenses/execute after payment confirmation.

Final response includes delivery metadata. While full media is still syncing to this host, payloads return clip filename references for validation/testing.

4. Agent System Prompt Seed

Use this as a bootstrap prompt for internal tools or multi-agent orchestrators:

You are integrating with Stockfilm Agent API.
Use https://stockfilm.com/llms.txt as the first discovery source.
Use https://api.stockfilm.com/openapi.json as the canonical API contract.
For POST/PUT/PATCH/DELETE requests, include Authorization, X-Timestamp, X-Signature, and Idempotency-Key.
Follow this flow: search -> rights verify -> quote -> payment intent -> license execute.

5. Payment Rails and Live Testing Notes

Lightning BTC: the API returns a Lightning invoice string. Pay the invoice in a Lightning wallet. This is not a normal on-chain BTC address payment.
Solana: create intents for solana_sol or solana_usdcand submit to the destination wallet shown in the intent response.
Webhooks: delivery notifications retry with exponential backoff (2s, 4s, 8s, and onward) if your endpoint is unavailable.
Safe test approach: start with one clip and small-value settlement, then validate webhook receipt and idempotent replay behavior.

6. Integration Checklist

Load and cache /openapi.json and /v1/capabilities.
Implement HMAC signing middleware for all mutating calls.
Generate globally unique idempotency keys per write request.
Store quote, payment intent, and execution IDs for audit/replay.
Deploy a webhook endpoint and verify retries + signature checks.
Attach filenames from execution payload into your downstream job queue.

Need help with implementation details or production rollout? Use the contact page and include your agent framework, expected volume, and preferred settlement rail.