> ## Documentation Index > Fetch the complete documentation index at: https://docs.nvisy.com/llms.txt > Use this file to discover all available pages before exploring further. # Start a run (detect) > Starts detection for a file and returns 202 with the run in the `running` state; the analysis runs in the background. Watch the run's status via the SSE stream at `.../runs/{runId}/events` (or re-read the run) and fetch the findings from `.../runs/{runId}/detections/` once it reaches `analyzed`. A repeated Idempotency-Key returns the existing run. ## OpenAPI ````yaml /api-reference/openapi.json post /workspaces/{workspaceSlug}/pipelines/{pipelineSlug}/runs/ openapi: 3.1.0 info: title: Nvisy API summary: Document processing and annotation platform description: >- Nvisy provides intelligent document processing, annotation, and analysis capabilities. This API enables document upload, OCR processing, embedding generation, and semantic search across your document collections. termsOfService: https://nvisy.com/legal/terms-of-service contact: name: Nvisy Support url: https://nvisy.com email: hello@nvisy.com license: name: Proprietary url: https://nvisy.com/license version: 0.1.0 servers: [] security: [] tags: - name: Accounts description: Account management and profile operations - name: Authentication description: Login, signup, and token management - name: Workspaces description: Workspace creation and management - name: Files description: File upload, download, and management - name: Members description: Workspace member management - name: Invites description: Workspace invitation handling - name: API Tokens description: API token management - name: Connections description: External provider connections - name: Pipelines description: Redaction pipeline configuration - name: Pipeline Runs description: Pipeline run execution and review - name: Policies description: Redaction policy configuration - name: Webhooks description: Webhook configuration - name: Notifications description: Account notification management - name: Health description: Service health checks paths: /workspaces/{workspaceSlug}/pipelines/{pipelineSlug}/runs/: post: tags: - Pipeline Runs summary: Start a run (detect) description: >- Starts detection for a file and returns 202 with the run in the `running` state; the analysis runs in the background. Watch the run's status via the SSE stream at `.../runs/{runId}/events` (or re-read the run) and fetch the findings from `.../runs/{runId}/detections/` once it reaches `analyzed`. A repeated Idempotency-Key returns the existing run. parameters: - in: path name: workspaceSlug description: URL-safe workspace identifier. required: true schema: description: URL-safe workspace identifier. type: string style: simple - in: path name: pipelineSlug description: URL slug of the pipeline, unique within its workspace. required: true schema: description: URL slug of the pipeline, unique within its workspace. type: string style: simple requestBody: description: >- Request payload to start a run (detect) over a file. Analyzes the file with the pipeline's configuration and returns the run, which holds the findings for review before redaction. content: application/json: schema: $ref: '#/components/schemas/CreatePipelineRun' required: true responses: '200': description: >- Response type for a pipeline run. A run is addressed by its own opaque id; the owning pipeline and workspace slugs are carried for context. content: application/json: schema: $ref: '#/components/schemas/PipelineRun' '202': description: >- Response type for a pipeline run. A run is addressed by its own opaque id; the owning pipeline and workspace slugs are carried for context. content: application/json: schema: $ref: '#/components/schemas/PipelineRun' '400': description: >- HTTP error response representation with security-conscious design. This struct contains all the information needed to serialize an error response, including the error name, message, HTTP status code, resource information, and user-friendly messages. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: >- HTTP error response representation with security-conscious design. This struct contains all the information needed to serialize an error response, including the error name, message, HTTP status code, resource information, and user-friendly messages. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- HTTP error response representation with security-conscious design. This struct contains all the information needed to serialize an error response, including the error name, message, HTTP status code, resource information, and user-friendly messages. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- HTTP error response representation with security-conscious design. This struct contains all the information needed to serialize an error response, including the error name, message, HTTP status code, resource information, and user-friendly messages. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- HTTP error response representation with security-conscious design. This struct contains all the information needed to serialize an error response, including the error name, message, HTTP status code, resource information, and user-friendly messages. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '415': description: 'Expected request with `Content-Type: application/json`' content: text/plain: schema: type: string '422': description: Failed to deserialize the JSON body into the target type content: text/plain: schema: type: string security: - BearerAuth: [] components: schemas: CreatePipelineRun: description: |- Request payload to start a run (detect) over a file. Analyzes the file with the pipeline's configuration and returns the run, which holds the findings for review before redaction. type: object properties: fileId: description: The file to analyze. type: string format: uuid scope: $ref: '#/components/schemas/ScopeParams' description: >- Per-document scope (languages, jurisdictions, document labels). Overrides the pipeline's `defaultScope` when present; absent falls back to the pipeline default. required: - fileId PipelineRun: description: >- Response type for a pipeline run. A run is addressed by its own opaque id; the owning pipeline and workspace slugs are carried for context. type: object properties: completedAt: description: When the run completed. type: string format: date-time error: description: Human-readable failure reason, present only when the run `failed`. type: string id: description: Opaque identifier of the run. allOf: - $ref: '#/components/schemas/RunId' inputFileId: description: Source document this run analyzes / redacts. type: string format: uuid inputFileName: description: >- Display name of the source document, for showing the run without a separate file lookup. `None` if the file was removed (e.g. by retention). type: string metadata: description: Non-encrypted metadata for filtering/display. allOf: - $ref: '#/components/schemas/RunMetadata' outputFileId: description: Redacted document produced by the run, once it completes. type: string format: uuid outputFileName: description: Display name of the redacted output, once the run completes. type: string pipelineSlug: description: Handle of the pipeline this run belongs to. allOf: - $ref: '#/components/schemas/Handle' startedAt: description: When the run started. type: string format: date-time status: description: |- Current run status. The detections are available to fetch from the run's `detections` endpoint once this reaches `analyzed`. allOf: - $ref: '#/components/schemas/PipelineRunStatus' triggerType: description: How the run was triggered. allOf: - $ref: '#/components/schemas/PipelineTriggerType' triggeredBy: description: Account that triggered the run. allOf: - $ref: '#/components/schemas/AccountRef' workspaceSlug: description: Handle of the workspace this run belongs to. allOf: - $ref: '#/components/schemas/Handle' required: - id - pipelineSlug - workspaceSlug - inputFileId - triggeredBy - triggerType - status - metadata - startedAt ErrorResponse: description: |- HTTP error response representation with security-conscious design. This struct contains all the information needed to serialize an error response, including the error name, message, HTTP status code, resource information, and user-friendly messages. type: object properties: message: description: User-friendly error message safe for client display type: string name: description: The error name/type identifier type: string resource: description: The resource that the error relates to (optional, set by handler) type: string suggestion: description: Helpful suggestion for resolving the error (optional) type: string validation: description: Validation error details for field-specific errors type: array items: $ref: '#/components/schemas/ValidationErrorDetail' required: - name - message ScopeParams: description: |- Caller-asserted scope for one request. A narrower wire projection of `elide::recognition::Scope`: `languages` and `countries` (typed, elide-native), plus elide's [`ScopeMetadata`] block for free-form classification strings (`tags`, `purpose`, `audience`). The engine assembles this plus a server-minted `correlation_id` and a policy-derived label catalog into the orchestrator's `Scope` at compile time. type: object properties: countries: description: |- Caller-asserted jurisdictions. When non-empty, recognizers that carry per-rule country scopes skip rules that match none of them. An empty list means "any": rules that declare countries still run as a permissive fallback so callers who don't assert a jurisdiction don't lose detections. type: array items: $ref: '#/components/schemas/CountryCode' languages: description: |- Caller-asserted languages for the analysis. Empty means the caller asserted none, leaving detection (if a language enricher runs) to fill in. allOf: - $ref: '#/components/schemas/Languages' default: [] metadata: description: |- Free-form request context: document tags, request purpose, output audience. See elide's [`ScopeMetadata`]. allOf: - $ref: '#/components/schemas/ScopeMetadata' RunId: description: Opaque run identifier (run_). type: string pattern: >- ^run_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ RunMetadata: description: Structured metadata for a pipeline run. type: object properties: error: description: Failure reason recorded when the run failed. type: string tags: description: Free-form labels attached to the run. type: array items: type: string Handle: description: >- Lowercase, dash-separated identifier used in URLs and as account handles. type: string maxLength: 32 minLength: 3 pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ PipelineRunStatus: description: >- Defines the execution status of a pipeline run. This enumeration corresponds to the `PIPELINE_RUN_STATUS` PostgreSQL enum and is used to track the current state of a pipeline execution. The detect phase has two states: `Queued` (the run is enqueued but no worker has begun) and `Analyzing` (a worker is actively analyzing). They settle into `Analyzed` (detection done, awaiting review), then `Completed` after redaction. oneOf: - description: Enqueued for detection; no worker has picked it up yet type: string const: queued - description: A worker is actively analyzing the document type: string const: analyzing - description: Detection done; awaiting reviewer verification type: string const: analyzed - description: Redaction applied; run finished type: string const: completed - description: Run failed with error type: string const: failed - description: Run was cancelled by user type: string const: cancelled PipelineTriggerType: description: >- Defines how a pipeline run was initiated. This enumeration corresponds to the `PIPELINE_TRIGGER_TYPE` PostgreSQL enum: a run is either started directly by a user or automatically by the system (for example, a file upload that the pipeline auto-redacts). oneOf: - description: Started directly by a user. type: string const: user - description: >- Started automatically by the system (e.g. a file upload auto-redacted by the pipeline). type: string const: system AccountRef: description: >- Public reference to the account behind a resource — whoever created it, uploaded it, triggered it, or performed it. Reused across resource responses so an account is always presented the same way: a handle plus an optional avatar. type: object properties: avatarUrl: description: Serve path of the account's avatar, when set. type: string displayName: description: Human-readable display name, when set. type: string username: description: Handle of the account. allOf: - $ref: '#/components/schemas/Handle' required: - username ValidationErrorDetail: description: Validation error details for field-specific errors. type: object properties: code: description: Error code for the validation failure type: string field: description: Field name that failed validation type: string message: description: Human-readable error message type: string params: description: Additional parameters related to the validation error type: object additionalProperties: true required: - field - code - message CountryCode: description: |- [ISO 3166-1] country, identified by its code. Wraps [`celes::Country`], a static table entry carrying the numeric, alpha-2, and alpha-3 codes together with the country's name. Because every value comes from that fixed table, a `CountryCode` is always a real, recognised country; there is no way to hold an invalid one. Used to scope region-sensitive recognizers (a phone-number or national-id pattern, say) to the country whose format they target. Serializes as its alpha-2 code (e.g. `"US"`). [ISO 3166-1]: https://www.iso.org/iso-3166-country-codes.html type: string Languages: description: |- List of [`Language`]s resolved for one text scan. Built by a detector (one entry per detected region) or by the caller asserting languages. Carried on a [`RecognizerContext`] so every recognizer and the context enhancer can consult the call's languages. [`RecognizerContext`]: crate::recognition::RecognizerContext type: array items: $ref: '#/components/schemas/Language' ScopeMetadata: description: >- Caller-asserted scope shared across every payload of one analysis. Built once with the `with_*` chain and passed by reference to the analyzer, which borrows it into a fresh [`RecognizerContext`] per payload. It holds only what the *caller* asserts about the analysis as a whole — languages, jurisdictions, document labels, the target catalog, a correlation id — none of which depends on the medium, so one [`Scope`] drives a text, image, or audio analysis alike. Per-medium regions (caller-supplied inclusions and exclusions, which are `M::Location`-typed) live in [`Annotations`], attached to the analyzer of that modality. The per-payload working state (NLP artifacts, detected languages) lives on the context, not here. [`RecognizerContext`]: super::RecognizerContext [`Annotations`]: super::annotation::Annotations Free-form, caller-asserted request context: the *document* it is about and the *request* driving it. Three axes of opaque classification strings elide neither ships nor interprets — a downstream policy layer chooses what `"medical"` or `"fraud_detection"` or `"auditor"` mean. They are read in two places: a recognizer may bias its detection on them (the LLM prompt lists them so the model attends to the right terms), and a scope-aware operator predicate may branch on them at selection time (redact the same document differently per [`audience`]). - [`tags`] classify the *document* (`"medical"`, `"gdpr-request"`). - [`purpose`] is why the request exists (`"fraud_detection"`). - [`audience`] is who the redacted output is for (`"support_agent"`, `"auditor"`) — the axis PCI-style "same document, two masks" branches on. [`tags`]: Self::tags [`purpose`]: Self::purpose [`audience`]: Self::audience type: object properties: audience: description: >- Who the redacted output is for (e.g. `"support_agent"`, `"auditor"`). The axis a per-audience redaction branches on: one detected document, selected differently per audience. May hold several. type: array default: [] items: type: string purpose: description: >- The caller-asserted business purpose driving this request (e.g. `"fraud_detection"`, `"gdpr_erasure_request"`). A scope-aware operator predicate may skip or swap a rule based on it; a recognizer may bias detection on it. `None` when the caller asserts no purpose. type: string default: null tags: description: |- Document-level classification tags (e.g. `"medical"`, `"gdpr-request"`). Recognizers may use these to bias their behavior for domain-specific terms; those that don't ignore the field. Named `tags`, not `labels`, to keep "label" reserved for the entity taxonomy ([`LabelRef`]/[`LabelCatalog`]): these classify the *document*, whereas the scope's catalog names the entity *types* to emit. [`LabelRef`]: crate::entity::LabelRef [`LabelCatalog`]: crate::entity::LabelCatalog type: array default: [] items: type: string Language: description: |- Single language detection result. Carries the language plus an optional confidence and an optional byte-offset [`LanguageSpan`]. Backends that don't expose confidence leave it `None`; single-language detectors that don't track per-region information leave `span` as `None`. The `provenance` field records whether the answer came from a detector or was asserted by the caller. type: object properties: confidence: $ref: '#/components/schemas/Confidence' description: Optional confidence score. `None` when not exposed. language: description: Language. allOf: - $ref: '#/components/schemas/LanguageTag' provenance: description: 'How this language was obtained: detected or caller-asserted.' allOf: - $ref: '#/components/schemas/LanguageProvenance' span: $ref: '#/components/schemas/LanguageSpan' description: |- Byte-offset range this detection applies to, when known. `None` means the whole text. required: - language - provenance Confidence: description: |- Confidence score in the closed range `0.0..=1.0`. Carried by every provenance [`AuditEvent`] (the `before`/`after` of a recognition, fusion, or calibration) and by the effective confidence of an [`Entity`]. The newtype enforces the range at construction so no downstream code has to defend against values outside `[0, 1]`. Distinct from [`ConfidenceThreshold`] so the two cannot be confused at a call site: a score is *produced* by detection, a threshold is a *cutoff* configured to filter scores. Compare the two with [`ConfidenceThreshold::passes`]. [`AuditEvent`]: crate::entity::audit::AuditEvent [`Entity`]: crate::entity::Entity type: number format: float LanguageTag: description: |- Well-formed [BCP 47] language tag, such as `en`, `en-US`, or `zh-Hant-HK`. Wraps [`oxilangtag::LanguageTag`] over a [`HipStr`] backing store, so short tags (the overwhelming common case) stay inline without a heap allocation. Parsing validates the tag's structure up front; the newtype therefore guarantees that any `LanguageTag` value in the model is syntactically valid. Used to record the language a recognizer is scoped to, or the detected language of a span of content. [BCP 47]: https://www.rfc-editor.org/info/bcp47 type: string LanguageProvenance: description: |- How a [`Language`]'s language was obtained. Lets consumers distinguish "a detector ran and got this answer" from "the caller asserted this language". An assertion may still carry an optional confidence, so this is independent of the confidence field. oneOf: - description: Produced by a language-detection backend. type: string const: detected - description: Asserted by the caller. type: string const: asserted LanguageSpan: description: |- Byte-offset range within the analyzed text. Attached to a [`Language`] when the detector knows the span its answer covers (mixed-language input produces multiple detections, each with a distinct span). Single-language detections from non-segmenting backends, and caller-asserted answers, typically leave the span as `None`. type: object properties: end: description: Byte offset of the span end in the original text. type: integer format: uint minimum: 0 start: description: Byte offset of the span start in the original text. type: integer format: uint minimum: 0 required: - start - end ````