> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turrisfi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Which API Is Mine?
> One question decides it: do you appoint agencies, or are you the agency?
Turris exposes **two APIs** over one platform. They share a host, an OAuth flow and an error envelope. They answer different questions, and **your credential works on exactly one of them.**
## The one question
You are an **MGA, carrier or wholesaler**. You want to read the agencies and producers you appoint: their licenses, appointments, documents and compliance standing.
**Carrier & MGA API** at `/v2/upstream/*`
You are an **agency or brokerage**. You want to read your own record: your entities and branches, your producers, your licenses and appointments, and the markets you place business with.
**Agency API** at `/v2/downstream/*`
If both descriptions sound partly true, you are an MGA that also holds retail business. You still get one credential per Turris organization, so the question is which organization you are calling as, not which you are.
## Why the path names you
From `v2` onward the segment after the version says which kind of organization the caller is:
```text theme={null}
https://public.api.live.turrisfi.com/v2/upstream/agents
^^^^^^^^
https://public.api.live.turrisfi.com/v2/downstream/producers
^^^^^^^^^^
```
The segment exists because an agency asking for "its licenses" means something different from a carrier asking for "its licenses". Without a word naming the caller, the two questions cannot share a path.
There is nothing to configure. You write the same literal word into your base URL every time, and it is the word for the organization your credential belongs to.
## What happens if you pick wrong
**A wrong-surface call returns `403`** with `errorType` set to `invalid_organization_category`.
That is a different 403 from the two others you may hit. Branch on `errorType`, never on the message text.
| `errorType` | Means |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `invalid_organization_category` | Right token, wrong surface. You are calling the other persona's path. |
| `product_feature_subscription_required` | Right surface, but your organization has not bought that area. The message names the feature to ask for. |
| `invite_limit_reached` | Only on `POST /v2/upstream/downstream-entity-associations/add` and `/invite`. You are at your associated-agency ceiling. |
## How to tell which credential you hold
Call the shared token test. It reports the surface your credential is for, so you never have to guess:
```bash theme={null}
curl "https://public.api.sandbox.turrisfi.com/v2/auth/test-oauth" \
-H "Authorization: Bearer "
```
The response carries `orgCategory`. Anything else in your integration follows from that one value.
| `orgCategory` | Surface | Status |
| ---------------------------- | ----------------------------------------------- | ------------------------- |
| `upstreamEntity` | Carrier & MGA API, `/v2/upstream/*` and `/v1/*` | Available |
| `downstreamEntity` | Agency API, `/v2/downstream/*` | Available |
| `enterpriseUpstreamEntity` | Enterprise carrier and MGA groups | Planned, not routable yet |
| `enterpriseDownstreamEntity` | Enterprise agency groups | Planned, not routable yet |
`orgCategory` is a four-value enum, so **do not branch with an if/else that treats "not `upstreamEntity`" as an agency.** The two enterprise values exist today and a credential carrying one would be misclassified by that shape. Match the value you expect and treat anything else as neither surface.
Four paths carry no persona segment, because the token itself identifies the organization: `auth/jwt`, `auth/test-oauth`, `auth/test-restricted-access-token` and `heartbeat`. Both surfaces call them the same way, **and this holds on `v1` as well as `v2`.** So an agency credential is served on `POST /v1/auth/jwt` and `GET /v1/heartbeat` even though every persona-scoped `v1` route refuses it. Prefer the `v2` paths anyway: only `GET /v2/auth/test-oauth` reports `orgCategory`.
## Versions differ by surface
| | Carrier & MGA API | Agency API |
| ---- | ----------------------------- | -------------------------------- |
| `v2` | 40 paths under `/v2/upstream` | 32 paths under `/v2/downstream` |
| `v1` | 47 paths, no persona segment | **Does not exist, and will not** |
`v1` predates the persona model and serves carriers only. That is the reason `v2` exists: without a persona in the path there was nowhere to put an agency-facing API. Both `v1` and `v2` are stable and supported. `/v2/upstream` carries every `v1` operation except seven: the four auth and heartbeat paths, which moved to the unsegmented `/v2/auth/*` and `/v2/heartbeat`, and three deprecated `dangerously-` endpoints, which have documented successors. See [versioning](/guides/versioning).
## The same records, two vocabularies
The two surfaces name the same rows differently, and each side's word is correct on its own side. This table is the only place both columns appear together, so it is worth reading once.
| Record | Carrier calls it | Agency calls it |
| ---------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------- |
| The carrier, MGA or wholesaler | **Upstream entity**, "you" | A **market** |
| The agency, or one of its branches | A **downstream entity**, an agency you appoint | **You**, or one of your own entities |
| The relationship between the two | A **downstream entity association**, id `downstreamEntityAssociationId` | A **market**, id `upstreamDownstreamAssociationId` |
| The licensed individual | An **agent** | A **producer** |
The relationship record has two id field names for one value. The carrier surface and every webhook payload call it `downstreamEntityAssociationId`. The agency surface calls it `upstreamDownstreamAssociationId`. They are the same identifier viewed from opposite ends, and neither is being renamed.
## What is shared, and where it lives
Everything on this tab applies to both surfaces: [authentication](/authentication), [environments](/guides/environments), [pagination](/guides/pagination), [rate limiting](/guides/rate-limiting), [request and response shape](/guides/request-response), [error handling](/guides/error-handling), [idempotency](/guides/idempotency), [versioning](/guides/versioning) and [security](/guides/security).
Everything specific to one surface lives on that surface's own tab, including its getting-started guide and its complete endpoint reference.
What it covers, what it cannot do, and how to make your first call.
What it covers, how credential scope works, and how to make your first call.
## Related topics
- [Support and Contact Information](/guides/support.md)
- [Introduction](/introduction.md)
- [Authentication](/authentication.md)