Docs / API
Brandloop API documentation
Brandloop's API surface is for authenticated developer workflows that need brand sources, assets, generation records, and scoped access. Public docs and OpenAPI are readable without a key; API calls require a scoped bearer credential.
Public reference
The generated API reference is available at `/developers/api`, and the machine-readable OpenAPI document is available at `/openapi.json`.
- Use `/developers/api` for the rendered reference.
- Use `/openapi.json` for contract inspection and client generation.
- Use scoped API keys for authenticated calls, not user passwords or provider credentials.
Credential boundary
API keys are product credentials controlled by Brandloop. Test and live are credential modes, not automatic sandbox guarantees. Scope a key to the capabilities an integration needs and revoke it when it is no longer needed.
Scopes, idempotency, and rate limits
Every operation requires a valid bearer API key. Resource operations also require the scope shown in the table below. Mutations require an Idempotency-Key header; replaying the same request is safe, while reusing a key with a different request returns a conflict. Each key receives 120 requests per 60-second window. Responses expose RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset; a 429 response adds Retry-After.
Package availability
The generated OpenAPI 3.1 document is implemented and public. The Brandloop TypeScript SDK is an internal preview in a private monorepo package; there is no supported public installation path or package release claim yet.
- OpenAPI is the public contract and client-generation source.
- The TypeScript SDK is source-available only inside the private monorepo.
- Agents should use authorized Brandloop contracts, never underlying provider credentials.
Brandloop API scopes
| Scope | Access | Use it for |
|---|---|---|
| brand_sources:read | Read | Inspect captured brand source records. |
| brand_sources:write | Write | Submit URLs for brand intelligence ingestion. |
| assets:read | Read | Fetch asset metadata and signed download instructions. |
| assets:write | Write | Create upload sessions for workspace media assets. |
| generations:read | Read | Inspect media generation jobs and outputs. |
| generations:write | Write | Create media generation jobs. |
Submit a brand source
bashKeep the key in an environment variable and give each mutation a stable idempotency key.
curl "$BRANDLOOP_BASE_URL/api/v1/brand-intelligence/sources" \
-H "Authorization: Bearer $BRANDLOOP_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: source-example-001" \
--data '{"url":"https://example.com","platform":"website"}'Handle a rate limit response
httpHTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 12
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 12
{"type":"https://brandloop.app/errors/rate_limited","title":"Request budget exceeded.","status":429,"code":"rate_limited","detail":"Too many requests. Retry after the window resets."}Limitations and boundaries
- Public documentation does not make API operations anonymous.
- API docs do not grant access to workspace data, provider tokens, billing mutations, or private storage.
- The internal SDK preview is not a published or supported package; use the OpenAPI contract for external client generation.
Common questions
- Can an AI agent read Brandloop API docs?
- Yes. The public reference and OpenAPI file are crawlable. Actual API operations still require scoped bearer access.
- Should integrations use provider credentials directly?
- No. Integrations should use Brandloop's public API contracts and scoped keys rather than underlying provider credentials.