---
title: "Organize File"
method: POST
path: "/v1/files/{asset_id}:organize"
tags: ["Public API v1 - Files"]
---

# Organize File

`POST /v1/files/{asset_id}:organize`

## Request

- Base URL: `https://api.corvio.ai`
- URL: `https://api.corvio.ai/v1/files/{asset_id}:organize`
- Auth: HTTP bearer

## Path parameters

- `asset_id` string, uuid, required

## Headers

- `X-Corvio-Caller-Model` string, nullable

## Request body

- PublicAssetOrganizeRequest
  - `instruction` string, required
  - `target_root_node_id` string, uuid, nullable
  - `additional_asset_ids` string[]
  - `processing_profile` 'auto' | 'economy' | 'standard' | 'deep'
  - `max_processing_profile` 'economy' | 'standard' | 'deep', nullable
  - `scan_mode` 'auto' | 'always' | 'off'
  - `skills_extraction_mode` 'auto' | 'always' | 'off'

## Response `202`

Successful Response

- PublicAssetOrganizationResponse
  - `operation_id` string, uuid, required
  - `asset_id` string, uuid, required
  - `asset_ids` string[]
  - `status` string, required
  - `phase` string, required
  - `processing` object: Requested/effective processing profile plus scan and Skill-evaluation policy. These are request receipts, not proof that an output was produced.
  - `result` object: State-aware bounded projection. Queued/running results may state that provisional outputs are omitted; a completed result may include visible artifacts, source_reconciliation, and skills_evaluation. Qualifying Skill evaluations include stable candidate IDs and typed page/node resource refs when the durable write exposed them.
  - `execution` object: Bounded execution receipts for this organization operation. A terminal response may include execution.durable_learning; candidate text and hidden Memory targets are never exposed.
  - `retry_after_seconds` integer, nullable: For queued or running work, the minimum suggested delay before another read. Absent at terminal state.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `links` object, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/corvio/apis/corvio-developer-api.md) · [All operations](https://skmtc.dev/corvio/apis/corvio-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/corvio/apis/corvio-developer-api/revisions/a5a77bb9619c?raw)