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

# Integration contracts

> Choose the right Insight integration surface and validate identities, metadata, responses, and background outcomes.

## Choose the surface

| Need                                                             | Surface                                    |
| ---------------------------------------------------------------- | ------------------------------------------ |
| Search, retrieve, create, or update documents and metadata       | Insight API                                |
| Populate indexing values or automate a Caseflow form             | [Script Engine](/scripts/introduction)     |
| Receive files and transform them through an ingestion pipeline   | [ContentFlow](/contentflow/introduction)   |
| Orchestrate document or Caseflow processes with tasks and timers | [Workflow Engine](/workflows/introduction) |
| Let an interactive assistant act with a person's access          | [AI assistant access](/mcp/introduction)   |

The API provides the public integration contract for the client and external systems. Use the interactive API reference and OpenAPI specification for your target environment and version. Prefer the v3 surface for new integrations; do not infer request fields or response shapes from screenshots or a different release.

## Agree on configuration first

Before implementation, record the target environment, integration identity, allowed operations, document types, keyword types and groups, and Caseflow application/class where relevant. Names and numeric IDs can differ between environments.

Check metadata requirements with the people maintaining [Document types and keywords](/configuration/introduction). File format, required fields, repeatable groups, and document access rights are part of a working integration, not just an API developer's concern.

## Verify more than a successful request

Use a test environment to check:

1. The dedicated identity authenticates and reaches only the intended records.
2. Required and optional metadata arrive in the expected types and groups.
3. The returned response is handled according to the selected API contract, including empty results and validation failures.
4. An accepted asynchronous operation reaches its intended final state, with a trace or correlation identifier retained for investigation.
5. A retry after an uncertain response does not accidentally create duplicate business work. Do not assume every operation is safe to repeat.

For sensitive content, a not-found response can also mean the caller cannot access the object. For administrative resources, forbidden generally indicates a missing permission. Check identity and access before concluding that the environment has lost a record.

## Support handover

Keep the integration owner, purpose, API client ID, granted group, environment, credential-rotation process, and recovery procedure with the integration's operational record. For failures, collect time, operation, response status, and correlation/trace ID when available. Do not copy bearer tokens or secrets into tickets.

## Where to read next

<Card title="Introduction to AI assistant access" icon="robot" href="/mcp/introduction" horizontal>
  Connect an AI assistant to Nobly Insight over the Model Context Protocol (MCP) — what it can reach, who decides, and what every request still has to pass.
</Card>