> ## Documentation Index
> Fetch the complete documentation index at: https://teardowns.aero/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Audience
> Restricting who can see a teardown's documents.
Every teardown has an **audience** field that controls who on the
platform can see its attached documents. Other fields (MSN, tail number,
location, etc.) are always visible to anyone with platform access only
documents are gated by audience.
## What you can set it to
| Value | Meaning |
| ------------------------------- | ----------------------------------------------------------------------------------- |
| `null` (or omit) | "Anyone with platform access" the default. |
| Non-empty list of company types | Only viewers whose org belongs to one of those company types can see the documents. |
The six allowed company types:
* `Airline`
* `Lessor`
* `OEM`
* `MRO`
* `Distributor`
* `Others`
## Default behaviour
A freshly-created teardown has `audience = null`. Anyone logged into
Teardowns.aero with `seller` or `buyer` access can see its documents.
For most teardowns, the default is just right. You'd typically only set an audience in special cases, for example, when a teardown contains operator-sensitive maintenance records, or when an OEM would like to keep their incident statements visible only to operators flying the same airframe.
## Two ways to set it
### 1. On the same call that uploads a document (recommended)
The document-upload endpoints accept an optional `audience` form field
a comma-separated string of company types:
```bash theme={null}
curl -X POST "$base_url/public/v1/teardown/documents/$teardown_id" \
-H "Authorization: Bearer $api_key" \
-H "X-Organization-Id: $org_id" \
-F "file=@/path/to/sensitive.pdf" \
-F "audience=Airline, MRO, Others"
```
One round trip:
* Uploads the file.
* Appends the URL to `documents[]`.
* Sets `audience = ["Airline", "MRO", "Others"]` on the teardown.
Case-insensitive (`mro, airline` works). Whitespace tolerated.
Duplicates dropped. Invalid values return `422 invalid_audience` with
the full allowed list and crucially, **before** the file is uploaded,
so you never get an orphan upload.
### 2. Via PATCH after the fact
If you've already uploaded the document and just want to change who
can see it, use the update endpoint:
```bash theme={null}
curl -X PATCH "$base_url/public/v1/teardowns/$teardown_id" \
-H "Authorization: Bearer $api_key" \
-H "X-Organization-Id: $org_id" \
-H "Content-Type: application/json" \
-d '{"audience": ["Airline","MRO"]}'
```
PATCH takes the JSON shape a real array, not a CSV. (Different
content type, different convention.) Setting `audience: null` clears
the restriction back to "anyone with platform access".
## Reading audience back
`GET /public/v1/teardowns/{id}` returns `audience` as part of the
response. It's `null` for never-set teardowns and an array for
restricted ones:
```jsonc theme={null}
{
"teardown_id": "...",
...
"audience": ["Airline", "MRO"],
"audience_set_at": "2026-05-26T10:00:00Z",
...
}
```
The `audience_set_at` timestamp records when the value was last changed
useful for support investigations.
## What the viewer sees
When a viewer's company type isn't in the audience list, they get the
teardown row in browse results but with the document URLs blanked out.
The teardown's existence isn't hidden just the doc URLs. (Hiding the
row entirely would break browse counts and surprise buyers who can
otherwise see the teardown listing.)
Three exceptions to the blanking rule:
1. **Same-org viewers always see all their own documents** the
audience never applies to your own org.
2. **Platform admins \[ Teardowns.aero ]** always see all documents.
3. **No audience set (`null`)** every viewer with platform access sees
the documents.
## Audit trail
Audience changes write a dedicated audit row:
* `audience.set` when `previous_audience` was `null`
* `audience.changed` when it was a different non-null list
Useful for "when did this become restricted, and who did it?" support
questions.