curl https://platform.u1.archetypeai.app/api/files \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "https://platform.u1.archetypeai.app/api/files?filename=training-data.csv" \
-H "Authorization: Bearer $ATAI_API_KEY"
import requests
import os
api_key = os.environ.get("ATAI_API_KEY")
response = requests.get(
"https://platform.u1.archetypeai.app/api/files",
headers={"Authorization": f"Bearer {api_key}"},
params={"limit": 100},
)
page = response.json()
for file in page["data"]:
print(f"{file['file_uid']} {file['file_id']} {file['file_status']}")
# Pass the cursor back verbatim as `after` to fetch the next page.
if page["has_more"]:
print(f"Next page cursor: {page['next_cursor']}")
const params = new URLSearchParams({
limit: "100",
});
const response = await fetch(
`https://platform.u1.archetypeai.app/api/files?${params}`,
{
headers: {
Authorization: `Bearer ${process.env.ATAI_API_KEY}`,
},
}
);
const page = await response.json();
for (const f of page.data) {
console.log(`${f.file_uid} ${f.file_id} ${f.file_status}`);
}
// Pass the cursor back verbatim as `after` to fetch the next page.
if (page.has_more) {
console.log(`Next page cursor: ${page.next_cursor}`);
}
{
"data": [
{
"file_id": "training-data.csv",
"file_uid": "fil_01k7x3q9m2v8n4p6r5t0w1y2z3",
"is_valid": true,
"file_type": "text/csv",
"num_bytes": 12483910,
"created_at": "2026-10-21T09:12:44Z",
"file_status": "FILE_STATUS_INGESTED",
"file_attributes": {
"num_rows": 50000,
"num_columns": 24,
"column_headers": ["timestamp", "value", "label"]
},
"ingested": true,
"file_index": 0,
"file_tags": {}
}
],
"has_more": true,
"next_cursor": "<cursor>",
"prev_cursor": null
}
{
"errors": [
{
"code": "unauthorized_request",
"message": "Unauthorized or invalid access.",
"suggestion": "Provide valid authentication credentials and ensure they have the required permissions.",
"error_uid": "err-xxxxxxxx"
}
]
}
Files API
List Files
List the files in the authenticated organization, with filters and cursor pagination
GET
/
api
/
files
curl https://platform.u1.archetypeai.app/api/files \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "https://platform.u1.archetypeai.app/api/files?filename=training-data.csv" \
-H "Authorization: Bearer $ATAI_API_KEY"
import requests
import os
api_key = os.environ.get("ATAI_API_KEY")
response = requests.get(
"https://platform.u1.archetypeai.app/api/files",
headers={"Authorization": f"Bearer {api_key}"},
params={"limit": 100},
)
page = response.json()
for file in page["data"]:
print(f"{file['file_uid']} {file['file_id']} {file['file_status']}")
# Pass the cursor back verbatim as `after` to fetch the next page.
if page["has_more"]:
print(f"Next page cursor: {page['next_cursor']}")
const params = new URLSearchParams({
limit: "100",
});
const response = await fetch(
`https://platform.u1.archetypeai.app/api/files?${params}`,
{
headers: {
Authorization: `Bearer ${process.env.ATAI_API_KEY}`,
},
}
);
const page = await response.json();
for (const f of page.data) {
console.log(`${f.file_uid} ${f.file_id} ${f.file_status}`);
}
// Pass the cursor back verbatim as `after` to fetch the next page.
if (page.has_more) {
console.log(`Next page cursor: ${page.next_cursor}`);
}
{
"data": [
{
"file_id": "training-data.csv",
"file_uid": "fil_01k7x3q9m2v8n4p6r5t0w1y2z3",
"is_valid": true,
"file_type": "text/csv",
"num_bytes": 12483910,
"created_at": "2026-10-21T09:12:44Z",
"file_status": "FILE_STATUS_INGESTED",
"file_attributes": {
"num_rows": 50000,
"num_columns": 24,
"column_headers": ["timestamp", "value", "label"]
},
"ingested": true,
"file_index": 0,
"file_tags": {}
}
],
"has_more": true,
"next_cursor": "<cursor>",
"prev_cursor": null
}
{
"errors": [
{
"code": "unauthorized_request",
"message": "Unauthorized or invalid access.",
"suggestion": "Provide valid authentication credentials and ensure they have the required permissions.",
"error_uid": "err-xxxxxxxx"
}
]
}
Requires version 2.0.0 or later of the Archetype platform.
Overview
This endpoint returns a cursor-paginated list of the files in your organization that you can see. It takes the same query parameters and returns the same page shape as List Files Metadata, and adds afilename filter for an exact name match. Files that
are being deleted or are already deleted aren’t listed. Filters are applied before pagination.
The list is ordered on the field named by sort, in the direction given by order. The default
is newest created_at first. Ties are broken on the file_uid, so the same request returns the
same page while no files change.
When paging, be sure to keep
sort and order the same.limit files (default 100, at most 1000). To read the next page, pass the
previous page’s next_cursor as after; to step back, pass its prev_cursor as before.
has_more refers to the direction being travelled. Cursors are opaque tokens tied to the sort
they were minted under and must not be constructed by the client.
Query Parameters
integer
default:"100"
Page size, between
1 and 1000. Values outside that range are clamped.string
Opaque cursor from a previous page’s
next_cursor (or its prev_cursor after paging
backward): returns the rows past it in the requested order. Mutually exclusive with before;
a cursor minted under a different sort is rejected with an HTTP 400 error.string
Opaque cursor from a previous page’s
prev_cursor (or its next_cursor after paging
backward): returns the rows before it in the requested order. Mutually exclusive with after.string
Filter results to a comma-delineated list of up to 50 MIME file types (e.g.
image/png,
text/csv,application/json). Omit to return files of all types.string
Case-insensitive substring match against file names. An empty string is ignored.
string
Exact match against file names. The page holds at most the one file with this name. An empty
string is ignored.
string
Specifies the field on which the returned list is ordered. Must be one of the following:
| Value | Description |
|---|---|
created_at | Sort by the time and date at which the file was created. Default value. |
file_id | Sort by the file’s name |
file_status | Sort by the file’s lifecycle status, in this order: uploading, registered, ingested, corrupt |
num_bytes | Sort by the size of the file in bytes |
string
Specifies whether sorting is performed in ascending order (
asc) or descending order
(desc). When sorting by created_at or num_bytes, this defaults to desc. When sorting by
file_status or file_id, this defaults to asc.Response
Returns one page of file metadata records, along with the cursors to move off it. When the page is past the end of the file list,data is empty and has_more is false.
array
required
The files on this page, in the requested
sort and order whether the page was reached with
after or before. Each record has the same shape as the response from Get
File.boolean
required
Whether more files exist in the direction this page was fetched.
string
Cursor continuing in the direction of travel: pass it as
after on a forward page, or as
before when this request itself used before. null when has_more is false.string
Cursor stepping back the way this page was reached: pass it as
before after a forward page,
or as after after a backward one. null when the request carried no cursor (the first page).400 error is returned for an invalid sort or order, when both after and before
are given, for a malformed cursor or one minted under another sort, or when file_type lists
more than 50 MIME types.
curl https://platform.u1.archetypeai.app/api/files \
-H "Authorization: Bearer $ATAI_API_KEY"
curl "https://platform.u1.archetypeai.app/api/files?filename=training-data.csv" \
-H "Authorization: Bearer $ATAI_API_KEY"
import requests
import os
api_key = os.environ.get("ATAI_API_KEY")
response = requests.get(
"https://platform.u1.archetypeai.app/api/files",
headers={"Authorization": f"Bearer {api_key}"},
params={"limit": 100},
)
page = response.json()
for file in page["data"]:
print(f"{file['file_uid']} {file['file_id']} {file['file_status']}")
# Pass the cursor back verbatim as `after` to fetch the next page.
if page["has_more"]:
print(f"Next page cursor: {page['next_cursor']}")
const params = new URLSearchParams({
limit: "100",
});
const response = await fetch(
`https://platform.u1.archetypeai.app/api/files?${params}`,
{
headers: {
Authorization: `Bearer ${process.env.ATAI_API_KEY}`,
},
}
);
const page = await response.json();
for (const f of page.data) {
console.log(`${f.file_uid} ${f.file_id} ${f.file_status}`);
}
// Pass the cursor back verbatim as `after` to fetch the next page.
if (page.has_more) {
console.log(`Next page cursor: ${page.next_cursor}`);
}
{
"data": [
{
"file_id": "training-data.csv",
"file_uid": "fil_01k7x3q9m2v8n4p6r5t0w1y2z3",
"is_valid": true,
"file_type": "text/csv",
"num_bytes": 12483910,
"created_at": "2026-10-21T09:12:44Z",
"file_status": "FILE_STATUS_INGESTED",
"file_attributes": {
"num_rows": 50000,
"num_columns": 24,
"column_headers": ["timestamp", "value", "label"]
},
"ingested": true,
"file_index": 0,
"file_tags": {}
}
],
"has_more": true,
"next_cursor": "<cursor>",
"prev_cursor": null
}
{
"errors": [
{
"code": "unauthorized_request",
"message": "Unauthorized or invalid access.",
"suggestion": "Provide valid authentication credentials and ensure they have the required permissions.",
"error_uid": "err-xxxxxxxx"
}
]
}
Was this page helpful?