> ## Documentation Index
> Fetch the complete documentation index at: https://docs.canary.effectiveai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Read your filing workspace

> Find filing Records across your Mission Controls and read them from any HTTP client or agent.

Use managed-filing reads for your filing workspace. Use [filing search](/guides/search-filings)
for the regulatory reference catalog. These resources have different IDs.
Creation, pre-review, and SERFF staging are not available through this resource yet.

## Authenticate

Use an ordinary user-owned Effective API key with MC and filing access. Read-only
keys can read. Resource-scoped, app/system, and record-bot keys are unsupported.
No Captain session or active UI is needed.

Set `EFFECTIVE_API_BASE_URL` to your deployment origin without `/api/v2`, and
provide `EFFECTIVE_API_KEY` through your client's secret environment. Verify the
caller with `GET /api/v2/users/me`.

## List filings

List across all active Mission Controls you can view in your tenant. There is no MC filter:

```bash theme={null}
curl --silent --show-error --fail-with-body --get \
  --header "Authorization: Bearer ${EFFECTIVE_API_KEY}" \
  --data-urlencode 'limit=20' \
  "${EFFECTIVE_API_BASE_URL%/}/api/v2/managed-filings"
```

The response has a `filings` array and nullable `nextCursor`. Summaries include
ID, canonical authorization scope (`mc:<MC UUID>`), display name, filing mode, company/jurisdiction/product IDs, tracking
numbers, description, and timestamps. Missing optional metadata is null.
`filingMode` distinguishes `managed`, read-only `reference`, and unclassified
legacy data (`null`). MC access alone does not grant access to private filings.

Repeat the limit with the returned cursor. Default page size is 50; maximum
is 100. Results are ordered by MC UUID ascending, then creation time descending
and filing ID ascending within each MC. Short/empty pages may have a continuation;
stop only at null. Cursors expire 24 hours after the first page. Changing caller
or page size invalidates them. Each call refreshes current MC and filing access;
revoked scopes are skipped. Restart the list to see newly accessible filings that
sort before your current position. No accessible filings returns an empty list.

## Read one filing

Set `FILING_ID` to a returned ID. No MC parameter is needed:

```bash theme={null}
curl --silent --show-error --fail-with-body \
  --header "Authorization: Bearer ${EFFECTIVE_API_KEY}" \
  "${EFFECTIVE_API_BASE_URL%/}/api/v2/managed-filings/${FILING_ID}"
```

Detail adds additional product references, dates/classification, and current
Records permissions. For a Reader, the permission portion is:

```json theme={null}
{
  "permissions": {
    "read": true,
    "edit": false,
    "manageAccess": false
  }
}
```

These are current permissions, not a list of available v2 write endpoints.
Later operations recheck them. References/unclassified filings never advertise
content editing; existing sharing administration remains separate. Private
grants, custom fields, internal context, and audit actors are not exposed.

## Recover from errors

* `401 unauthenticated`: verify the credential and whether its type is supported.
* `403 forbidden`: credential is not permitted for this operation.
* `404 not_found`: filing missing or invisible; these cases are indistinguishable.
* `400 invalid_cursor`: restart the list.
* `400 invalid_request`: correct input; unknown/repeated scalar fields are rejected.
* `503 temporarily_unavailable`: respect `Retry-After` before retrying the read.

Use these same calls from Codex, another harness, or an application. Store
returned IDs rather than deriving them from tracking numbers or chat state.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.