Prepare a filing

Find, create, and edit filing Records and documents from any HTTP client or agent.

Use managed-filing reads for your filing workspace. Use filing search for the regulatory reference catalog. These resources have different IDs. 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:

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:

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:

{
  "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.
• 409 conflict: the filing is read-only, a schedule position is occupied, a dependency prevents removal, or inputs changed during validation.
• 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.

Create and edit a filing

Use a write-capable user key with MC edit access. The MC must already have filings, companies, jurisdictions, and products registered; item operations also need filing_items. An administrator can configure these in the Records UI. Find reference IDs through the existing GET /api/v1/mission-controls/{mcId}/records/reference-options?targetKind=system_record&recordType=companies API; repeat with jurisdictions and products. Follow that endpoint’s pagination.

toiCode and subToiCode use NAIC registry values. A sub-TOI requires its parent TOI. Discover choices with GET /api/v1/mission-controls/{mcId}/records/types/filings/fields/toiCode/options?limit=25&query=property and discover matching sub-TOIs with GET /api/v1/mission-controls/{mcId}/records/types/filings/fields/subToiCode/options?dependencyValue=01.0&limit=25. The options endpoint supports query to narrow the results. When changing a TOI, change or clear an incompatible sub-TOI in the same request. PATCH checks the resulting filing, including fields you leave unchanged.

Create with POST /api/v2/managed-filings and Content-Type: application/json:

{
  "scope": "mc:your-mc-slug",
  "companyId": "<company UUID>",
  "jurisdictionId": "<jurisdiction UUID>",
  "primaryProductId": "<product UUID>",
  "filingType": "form",
  "description": "New forms filing"
}

Replace placeholders with the authorized reference IDs. The response is 201, includes the created filing and canonical scope, and supplies its detail URL in Location. API-key creation does not start a Captain session.

Use PATCH /api/v2/managed-filings/{filingId} to change selected fields:

{ "description": "Updated filing", "effectiveFromNew": "2027-01-01" }

Omitted fields stay unchanged; null clears nullable values. Editors need both MC and filing edit access. Imported/reference and unclassified filings cannot be prepared. Scope, ownership, sharing, and filing mode cannot be edited here.

Upload and attach documents

Use the existing Vault upload flow with the same bearer credential. No session is required. Choose a writable folder visible to the intended collaborators.

1. POST /api/v1/vault/upload/init with {"targetUri":"personal://filing-preparation","files":[{"path":"form.pdf","size":1234,"mimeType":"application/pdf"}],"onConflict":"fail"}. Supply the actual byte count and your target folder. Personal files may need separate sharing before another collaborator can read their bytes.
2. PUT the local PDF bytes to files[0].signedUrl with exactly the returned files[0].headers. Do not send the Effective bearer credential to storage.
3. POST /api/v1/vault/upload/complete with {"confirmations":[{"uploadToken":"<token from init>"}]}. Check each results[].success; use the successful result’s artifact.id.
4. POST /api/v2/managed-filings/{filingId}/items with the resulting ID:

{
  "artifactId": "<uploaded form UUID>",
  "scheduleType": "form",
  "scheduleSeqNo": 1,
  "attachments": [{ "artifactId": "<uploaded redline UUID>", "artifactName": "redline.pdf" }]
}

Omit both schedule fields to add preparation notes or other unscheduled documents. The server checks access to every attached file. Working attachments follow the file’s current content; submission recording pins versions later.

Use GET /api/v2/managed-filings/{filingId}/items?limit=50 to list items. Follow nextCursor with the same filing and limit until null. Item cursors expire after 24 hours. Reading an item does not itself grant permission to read its file bytes.

Use PATCH /api/v2/managed-filings/{filingId}/items/{itemId} with a new artifactId to replace the working file reference. Send both schedule fields as null to remove an assignment, or both values to assign a position. Updating an item does not change retained submission contents.

Use DELETE /api/v2/managed-filings/{filingId}/items/{itemId} to remove an item. It returns 204, retains file bytes, and rejects removal when dependencies require the item. A repeated delete returns 404.

Create/add requests are not idempotent. After a lost response, inspect the filing or item list before retrying. Updates use last-write-wins semantics: read current values before editing. These preparation calls neither stage nor submit to SERFF.