Core Concepts

Understand how Orsa works under the hood.

Brand Data Model

When you call /v1/brand/retrieve, Orsa returns a comprehensive brand profile:

{
  "name": "Stripe",
  "domain": "stripe.com",
  "description": "Financial infrastructure for the internet.",
  "logos": [
    { "url": "https://...", "type": "svg", "theme": "light" },
    { "url": "https://...", "type": "png", "theme": "dark" }
  ],
  "colors": ["#635BFF", "#0A2540", "#00D4AA"],
  "fonts": ["Inter", "system-ui"],
  "industry": "Financial Technology",
  "naics_code": "522320",
  "socials": {
    "twitter": "https://twitter.com/stripe",
    "linkedin": "https://linkedin.com/company/stripe",
    "github": "https://github.com/stripe"
  },
  "meta": {
    "title": "Stripe | Payment Processing Platform",
    "description": "...",
    "favicon": "https://stripe.com/favicon.ico"
  }
}

How It Works

1. Fetch — Orsa loads the target domain using a headless browser
2. Extract — Multiple extractors run in parallel: logos, colors, fonts, social links, metadata, industry classification
3. Assemble — Results are merged, deduplicated, and scored for confidence
4. Cache — The assembled profile is cached for fast subsequent lookups

Caching

Orsa uses a two-tier cache for performance:

• Cached responses are free (0 credits).
• You can force a fresh fetch by passing ?refresh=true (costs normal credits).

Credits

Every API call costs a specific number of credits based on the endpoint and computational cost:

Credit Tracking

• Check your balance anytime via the dashboard (opens in a new tab) or the /v1/health endpoint
• Set up credit alerts in Settings to get notified at 10% remaining
• Credits reset monthly on your billing date
• Unused credits do not roll over

Rate Limits

When you hit a rate limit, the API returns 429 Too Many Requests with a Retry-After header indicating seconds to wait.

Error Handling

All errors follow a consistent format:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Retry after 2 seconds.",
    "status": 429
  }
}

Common error codes: