# AUTO-GENERATED tier-A mirror spec — do not edit. # Source: openapi/runtime/ingestion-rules.yaml (runtime 0.71.2) # + policy: openapi/mirror-policies/ingestion-rules.json # Regenerate: node scripts/generate-mirror-specs.mjs openapi: 3.0.3 info: title: naturali.ai — Ingestion Rules API version: 1.0.0 description: >- Ingestion rules: how a document becomes retrievable — which files a rule matches, the converter that turns them into text, and the chunking and embedding the resulting pass applies. A fully runtime-backed module — this spec is generated verbatim from the runtime's own, re-rooted under /v1/projects/{project_id}. The project in the path is authorized by naturali and enforced upstream by the project's scoped credential. This module mirrors the upstream runtime verbatim (tier A, #304): paths are the runtime's own re-rooted under /v1/projects/{project_id}, and every field, method, status code and error shape passes through unchanged. Errors raised by the runtime arrive in its envelope; errors raised by naturali itself (authentication, project resolution, an unreachable runtime) use naturali's. contact: name: naturali.ai url: https://naturali.ai servers: - url: "{baseUrl}" description: Host of your naturali.ai deployment; every path carries the /v1 prefix. variables: baseUrl: description: Base host URL. default: https://api.naturali.ai tags: - name: Ingestion Rules description: Route content types to converter tools or agents during ingestion security: - bearerAuth: [] - oauth2: - mcp:access paths: /v1/projects/{project_id}/ingestion-rules: get: tags: - Ingestion Rules summary: List ingestion rules description: Returns the ingestion rules for a project operationId: listIngestionRules parameters: - name: limit in: query description: Number of results per page schema: type: integer minimum: 1 maximum: 100 default: 50 - name: offset in: query description: Number of results to skip schema: type: integer default: 0 responses: "200": description: List of ingestion rules content: application/json: schema: type: object required: - data - total - limit - offset properties: data: type: array items: $ref: "#/components/schemas/IngestionRule" total: type: integer limit: type: integer offset: type: integer "401": description: Unauthorized "403": description: Forbidden "500": description: Internal server error post: tags: - Ingestion Rules summary: Create an ingestion rule description: Creates a rule mapping a content_type glob to a converter. Exactly one of tool_id or agent_id must be set. operationId: createIngestionRule requestBody: required: true content: application/json: schema: type: object required: - content_type_glob additionalProperties: false properties: content_type_glob: type: string description: MIME type glob matched against a file's content_type. At most 4 wildcards and 255 characters — a MIME glob needs one on each side of the slash at most. maxLength: 255 example: image/* tool_id: x-naturali-ref: tools type: string description: Converter tool id (mutually exclusive with agent_id) example: tool_V1StGXR8Z5jdHi6B agent_id: x-naturali-ref: agents type: string description: Converter agent id (mutually exclusive with tool_id) example: agent_V1StGXR8Z5jdHi6B action: type: string description: Operation id, required for mcp tool converters preset_parameters: type: object description: Merged into the tool input before invocation (tool converters only) native_extraction: type: string enum: - first - skip description: "For native types (PDF/text): `first` (default) converts only when native extraction yields no text; `skip` always converts." file_delivery: type: string enum: - base64 - download_url description: How the file reaches a tool converter (default base64) chunk_strategy: type: string enum: - page - whole - size description: Default chunk strategy, overridable per ingest request chunk_size: type: integer description: Default window size in characters for the size strategy chunk_overlap: type: integer description: Default overlap in characters for the size strategy metadata: description: Arbitrary JSON metadata allOf: - $ref: "#/components/schemas/MetadataBag" responses: "201": description: Ingestion rule created content: application/json: schema: $ref: "#/components/schemas/IngestionRule" "400": description: Validation failed (e.g. tool_id and agent_id both set or both missing) "401": description: Unauthorized "403": description: Forbidden "409": description: A rule for this content_type_glob already exists in the project "500": description: Internal server error parameters: - $ref: "#/components/parameters/ProjectId" /v1/projects/{project_id}/ingestion-rules/{ingestion_rule_id}: get: tags: - Ingestion Rules summary: Get an ingestion rule description: Returns a specific ingestion rule operationId: getIngestionRule x-naturali-resource: kind: ingestionRule from: ingestion_rule_id parameters: - name: ingestion_rule_id in: path required: true description: Ingestion rule ID schema: type: string example: igr_V1StGXR8Z5jdHi6B responses: "200": description: Ingestion rule details content: application/json: schema: $ref: "#/components/schemas/IngestionRule" "401": description: Unauthorized "403": description: Forbidden "404": description: Ingestion rule not found patch: tags: - Ingestion Rules summary: Update an ingestion rule description: Updates fields of an ingestion rule operationId: updateIngestionRule x-naturali-resource: kind: ingestionRule from: ingestion_rule_id parameters: - name: ingestion_rule_id in: path required: true description: Ingestion rule ID schema: type: string requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: content_type_glob: type: string description: MIME type glob matched against a file's content_type. At most 4 wildcards and 255 characters. maxLength: 255 tool_id: x-naturali-ref: tools type: string nullable: true agent_id: x-naturali-ref: agents type: string nullable: true action: type: string nullable: true preset_parameters: type: object nullable: true native_extraction: type: string enum: - first - skip file_delivery: type: string enum: - base64 - download_url chunk_strategy: type: string enum: - page - whole - size - null nullable: true description: Send `null` to clear the rule's override and fall back to the per-request default. chunk_size: type: integer nullable: true chunk_overlap: type: integer nullable: true metadata: $ref: "#/components/schemas/NullableMetadataBag" responses: "200": description: Ingestion rule updated content: application/json: schema: $ref: "#/components/schemas/IngestionRule" "400": description: Validation failed "401": description: Unauthorized "403": description: Forbidden "404": description: Ingestion rule not found "409": description: A rule for this content_type_glob already exists in the project delete: tags: - Ingestion Rules summary: Delete an ingestion rule description: Deletes an ingestion rule operationId: deleteIngestionRule x-naturali-resource: kind: ingestionRule from: ingestion_rule_id parameters: - name: ingestion_rule_id in: path required: true description: Ingestion rule ID schema: type: string responses: "204": description: Ingestion rule deleted "401": description: Unauthorized "403": description: Forbidden "404": description: Ingestion rule not found parameters: - $ref: "#/components/parameters/ProjectId" components: schemas: IngestionRule: type: object properties: id: type: string example: igr_V1StGXR8Z5jdHi6B project_id: x-naturali-ref: projects type: string content_type_glob: type: string example: image/* tool_id: x-naturali-ref: tools type: string nullable: true agent_id: x-naturali-ref: agents type: string nullable: true action: type: string nullable: true preset_parameters: type: object nullable: true native_extraction: type: string enum: - first - skip file_delivery: type: string enum: - base64 - download_url chunk_strategy: type: string nullable: true chunk_size: type: integer nullable: true chunk_overlap: type: integer nullable: true metadata: $ref: "#/components/schemas/NullableMetadataBag" created_at: type: string format: date-time updated_at: type: string format: date-time MetadataBag: type: object description: >- Caller-owned annotations on a resource, stored as the object they were written as: the types a value was written with are the types a read returns, so a filter can ask an ordering question about a number. Unlike other body fields, keys are stored and returned verbatim in the casing supplied — they are not converted between snake_case and camelCase. No key is reserved, and that is the point: every piece of state the platform owns lives in its own typed column, so nothing written here reaches platform state. The platform never reads the bag — it is not an IAM context, not a policy input and not part of a prompt — which is what separates it from a tag bag. example: author: John revision: 2 NullableMetadataBag: type: object nullable: true description: A `MetadataBag` on a field where `null` is meaningful — a full-replacement update that clears the bag, or a record whose bag was never set. example: author: John revision: 2 parameters: ProjectId: name: project_id in: path required: true description: Project public ID (proj_ prefix). schema: type: string example: proj_V1StGXR8Z5jdHi6B securitySchemes: bearerAuth: type: http scheme: bearer description: A naturali API key (nat_sk_…) or a session JWT. oauth2: type: oauth2 description: "A connected app's OAuth access token, issued by this API's authorization server (discovery: /.well-known/oauth-authorization-server). Its one scope carries every operation, confined to the projects the user chose when approving the app." flows: authorizationCode: authorizationUrl: https://api.naturali.ai/authorize tokenUrl: https://api.naturali.ai/token refreshUrl: https://api.naturali.ai/token scopes: mcp:access: Every operation this API serves, on the projects the grant covers.