Attach existing files to a directory (folder)

POST

directories

{directoryId}

documents

curl --request POST \
  --url https://api.orion.file.ai/prod/v1/directories/{directoryId}/documents \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "fileIds": [
    "649e2d2d2d2d2d2d2d2d2d2d",
    "649e2d2d2d2d2d2d2d2d2d2e"
  ]
}
'

import requests

url = "https://api.orion.file.ai/prod/v1/directories/{directoryId}/documents"

payload = { "fileIds": ["649e2d2d2d2d2d2d2d2d2d2d", "649e2d2d2d2d2d2d2d2d2d2e"] }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({fileIds: ['649e2d2d2d2d2d2d2d2d2d2d', '649e2d2d2d2d2d2d2d2d2d2e']})
};

fetch('https://api.orion.file.ai/prod/v1/directories/{directoryId}/documents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
  "created": [
    "649e2d2d2d2d2d2d2d2d2d2d"
  ],
  "conflicted": [
    "649e2d2d2d2d2d2d2d2d2d2e"
  ],
  "rejected": [
    "649e2d2d2d2d2d2d2d2d2d2f"
  ]
}

Request · Response · Guide: Folders

More details

A file can belong to many directories at once. Use this endpoint for reference data that several folders need — price lists, rate cards, holiday calendars, monthly listings. Uploading the same file once per folder creates a separate file each time and is charged a separate extraction each time; attaching reuses the single original.Path Parameters:

directoryId (required): The directory to attach the files to

Request Body:

fileIds (string[], required): Ids of existing files to attach. At least 1, at most 100. Repeated ids are collapsed.

Response: Every id you send is returned in exactly one of three arrays, so a partial success is never silent:

created: newly attached by this request
conflicted: already attached before this request
rejected: not resolvable by this API key

Notes:

The endpoint is safe to retry. Re-attaching a file reports it as conflicted and creates no duplicate.
An id in rejected may be unknown, deleted, or owned by another workspace. The cases are not distinguished.
Attaching to several directories is one call per directory, each authorised on its own.
Directories that have a workflow are rejected with a 422, and so are their immediate subfolders — a file added to a subfolder drives the parent folder’s workflow. Deeper descendants are unaffected, since a workflow further up is not driven by the attach. Advancing a workflow on attach is not supported yet, and attaching without it would leave the folder in a half-applied state.
directoryId is echoed back in canonical lowercase form regardless of the case you send.

Authorizations

x-api-key

string

header

required

API key for authentication

Headers

Idempotency-Key

string

Optional opaque key (max 255 chars, UUIDv4 recommended) making this request idempotent for 24h: a retry with the same key and body replays the original response with Idempotent-Replayed: true.

Path Parameters

directoryId

string

required

Body

application/json

fileIds

string[]

required

Ids of existing files to attach, at most 100 per request. Repeated ids are collapsed. An id this key cannot see is reported in rejected rather than failing the request.

Required array length: 1 - 100 elements

Example:

[
  "649e2d2d2d2d2d2d2d2d2d2d",
  "649e2d2d2d2d2d2d2d2d2d2e"
]

Response

The attach request was processed. Check created, conflicted and rejected for the per-file outcome — a response where every id is rejected is still a 201.

directoryId

string

required

The directory the documents were attached to.

Example:

"649e2d2d2d2d2d2d2d2d2d2d"

created

string[]

required

Ids newly attached to the directory by this request.

Example:

["649e2d2d2d2d2d2d2d2d2d2d"]

conflicted

string[]

required

Ids already attached before this request. Re-attaching is not an error and creates no duplicate row, which makes the endpoint safe to retry.

Example:

["649e2d2d2d2d2d2d2d2d2d2e"]

rejected

string[]

required

Ids this API key cannot resolve — unknown, deleted, or belonging to another workspace. The three cases are deliberately not distinguished: telling a caller that an id exists but is not theirs would leak another tenant's data.

Example:

["649e2d2d2d2d2d2d2d2d2d2f"]

Attach existing files to a directory (folder)

curl --request POST \
  --url https://api.orion.file.ai/prod/v1/directories/{directoryId}/documents \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "fileIds": [
    "649e2d2d2d2d2d2d2d2d2d2d",
    "649e2d2d2d2d2d2d2d2d2d2e"
  ]
}
'

import requests

url = "https://api.orion.file.ai/prod/v1/directories/{directoryId}/documents"

payload = { "fileIds": ["649e2d2d2d2d2d2d2d2d2d2d", "649e2d2d2d2d2d2d2d2d2d2e"] }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({fileIds: ['649e2d2d2d2d2d2d2d2d2d2d', '649e2d2d2d2d2d2d2d2d2d2e']})
};

fetch('https://api.orion.file.ai/prod/v1/directories/{directoryId}/documents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "directoryId": "649e2d2d2d2d2d2d2d2d2d2d",
  "created": [
    "649e2d2d2d2d2d2d2d2d2d2d"
  ],
  "conflicted": [
    "649e2d2d2d2d2d2d2d2d2d2e"
  ],
  "rejected": [
    "649e2d2d2d2d2d2d2d2d2d2f"
  ]
}

Get started

Endpoints

Attach existing files to a directory (folder)

Authorizations

Headers

Path Parameters

Body

Response