Get File Metadata - Archetype AI Documentation

curl https://api.u1.archetypeai.app/v0.5/files/metadata/test_image.jpg \
  -H "Authorization: Bearer $ATAI_API_KEY"

import requests
import os

api_key = os.environ.get("ATAI_API_KEY")
file_id = "file-abc123"

response = requests.get(
    "https://api.u1.archetypeai.app/v0.5/files/metadata/test_image.jpg",
    headers={"Authorization": f"Bearer {api_key}"}
)

print(response.json())

const fileId = "file-abc123";

const response = await fetch(
  `https://api.u1.archetypeai.app/v0.5/files/metadata/${fileId}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.ATAI_API_KEY}`,
    },
  }
);

const metadata = await response.json();
console.log(metadata);

{
  "file_id": "file-abc123",
  "file_uid": "8f2c1e5a-7b3d-4d9e-9c1a-2f5b7d8e4a6c",
  "is_valid": true,
  "file_type": "image/png",
  "num_bytes": 482931,
  "file_status": "FILE_STATUS_INGESTED",
  "file_attributes": {
    "width": 1920,
    "height": 1080,
    "num_channels": 3,
    "channel_bands": ["R", "G", "B"]
  },
  "ingested": true,
  "file_index": 0,
  "file_tags": {}
}

{
  "file_id": "file-def456",
  "file_uid": "1d4f9b2e-3a8c-4e1d-bb02-7d6c9f0a3b51",
  "is_valid": true,
  "file_type": "text/csv",
  "num_bytes": 12483910,
  "file_status": "FILE_STATUS_INGESTED",
  "file_attributes": {
    "num_rows": 50000,
    "num_columns": 24,
    "column_headers": ["timestamp", "value", "label"]
  },
  "ingested": true,
  "file_index": 1,
  "file_tags": {}
}

{
  "file_id": "file-large-789",
  "file_uid": "9a0b1c2d-3e4f-5061-7283-94a5b6c7d8e9",
  "is_valid": true,
  "file_type": "video/mp4",
  "num_bytes": 4831785472,
  "file_status": "FILE_STATUS_INGESTED",
  "file_attributes": {
    "metadata_status": "not_extracted"
  },
  "ingested": true,
  "file_index": 2,
  "file_tags": {}
}

{
  "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"
    }
  ]
}

{
  "errors": [
    {
      "code": "file_not_found",
      "message": "No file with the given file_id was found for the organization.",
      "suggestion": "Verify the file_id and that the file has not been deleted.",
      "error_uid": "err-xxxxxxxx"
    }
  ]
}

GET

files

metadata

{file_id}

curl https://api.u1.archetypeai.app/v0.5/files/metadata/test_image.jpg \
  -H "Authorization: Bearer $ATAI_API_KEY"

import requests
import os

api_key = os.environ.get("ATAI_API_KEY")
file_id = "file-abc123"

response = requests.get(
    "https://api.u1.archetypeai.app/v0.5/files/metadata/test_image.jpg",
    headers={"Authorization": f"Bearer {api_key}"}
)

print(response.json())

const fileId = "file-abc123";

const response = await fetch(
  `https://api.u1.archetypeai.app/v0.5/files/metadata/${fileId}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.ATAI_API_KEY}`,
    },
  }
);

const metadata = await response.json();
console.log(metadata);

{
  "file_id": "file-abc123",
  "file_uid": "8f2c1e5a-7b3d-4d9e-9c1a-2f5b7d8e4a6c",
  "is_valid": true,
  "file_type": "image/png",
  "num_bytes": 482931,
  "file_status": "FILE_STATUS_INGESTED",
  "file_attributes": {
    "width": 1920,
    "height": 1080,
    "num_channels": 3,
    "channel_bands": ["R", "G", "B"]
  },
  "ingested": true,
  "file_index": 0,
  "file_tags": {}
}

{
  "file_id": "file-def456",
  "file_uid": "1d4f9b2e-3a8c-4e1d-bb02-7d6c9f0a3b51",
  "is_valid": true,
  "file_type": "text/csv",
  "num_bytes": 12483910,
  "file_status": "FILE_STATUS_INGESTED",
  "file_attributes": {
    "num_rows": 50000,
    "num_columns": 24,
    "column_headers": ["timestamp", "value", "label"]
  },
  "ingested": true,
  "file_index": 1,
  "file_tags": {}
}

{
  "file_id": "file-large-789",
  "file_uid": "9a0b1c2d-3e4f-5061-7283-94a5b6c7d8e9",
  "is_valid": true,
  "file_type": "video/mp4",
  "num_bytes": 4831785472,
  "file_status": "FILE_STATUS_INGESTED",
  "file_attributes": {
    "metadata_status": "not_extracted"
  },
  "ingested": true,
  "file_index": 2,
  "file_tags": {}
}

{
  "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"
    }
  ]
}

{
  "errors": [
    {
      "code": "file_not_found",
      "message": "No file with the given file_id was found for the organization.",
      "suggestion": "Verify the file_id and that the file has not been deleted.",
      "error_uid": "err-xxxxxxxx"
    }
  ]
}

Overview

This endpoint returns the full metadata record for a specific file in the authenticated organization, including file status, size, and type-specific attributes (image dimensions, tabular shape, etc.).

Path Parameters

file_id

string

required

Identifier of the file whose metadata to fetch

Response

file_id

string

Identifier of the file

file_uid

string

Internal unique identifier of the file

is_valid

boolean

Whether the metadata record is valid

file_type

string

MIME type of the file (e.g. image/png, text/csv)

num_bytes

integer

Size of the file in bytes

file_status

string

Lifecycle status of the file. One of:

FILE_STATUS_UNKNOWN
FILE_STATUS_REGISTERED
FILE_STATUS_INGESTING
FILE_STATUS_INGESTED
FILE_STATUS_IN_MEMORY
FILE_STATUS_IN_COLD_STORAGE
FILE_STATUS_CORRUPT

ingested

boolean

Whether the file has completed ingestion

file_index

integer

Index of this file within the organization’s file list

file_tags

object

Key/value tags attached to the file (empty object if no tags)

file_attributes

object

Type-specific attributes for the file. The shape varies by file type:

Show image attributes

width

integer

Image width in pixels

height

integer

Image height in pixels

num_channels

integer

Number of color channels

channel_bands

array

Channel band labels (e.g. ["R", "G", "B"])

Show tabular attributes

num_columns

integer

Number of columns

column_headers

array

Column header names

num_rows

integer

Number of rows. Only present when the platform was able to extract row counts at upload time — large files and direct-to-cloud uploads typically omit this field.

Show metadata not extracted

metadata_status

string

not_extracted — file was too large for inline metadata extraction. Contact platform maintainers if you need metadata for this file.

curl https://api.u1.archetypeai.app/v0.5/files/metadata/test_image.jpg \
  -H "Authorization: Bearer $ATAI_API_KEY"

import requests
import os

api_key = os.environ.get("ATAI_API_KEY")
file_id = "file-abc123"

response = requests.get(
    "https://api.u1.archetypeai.app/v0.5/files/metadata/test_image.jpg",
    headers={"Authorization": f"Bearer {api_key}"}
)

print(response.json())

const fileId = "file-abc123";

const response = await fetch(
  `https://api.u1.archetypeai.app/v0.5/files/metadata/${fileId}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.ATAI_API_KEY}`,
    },
  }
);

const metadata = await response.json();
console.log(metadata);

{
  "file_id": "file-abc123",
  "file_uid": "8f2c1e5a-7b3d-4d9e-9c1a-2f5b7d8e4a6c",
  "is_valid": true,
  "file_type": "image/png",
  "num_bytes": 482931,
  "file_status": "FILE_STATUS_INGESTED",
  "file_attributes": {
    "width": 1920,
    "height": 1080,
    "num_channels": 3,
    "channel_bands": ["R", "G", "B"]
  },
  "ingested": true,
  "file_index": 0,
  "file_tags": {}
}

{
  "file_id": "file-def456",
  "file_uid": "1d4f9b2e-3a8c-4e1d-bb02-7d6c9f0a3b51",
  "is_valid": true,
  "file_type": "text/csv",
  "num_bytes": 12483910,
  "file_status": "FILE_STATUS_INGESTED",
  "file_attributes": {
    "num_rows": 50000,
    "num_columns": 24,
    "column_headers": ["timestamp", "value", "label"]
  },
  "ingested": true,
  "file_index": 1,
  "file_tags": {}
}

{
  "file_id": "file-large-789",
  "file_uid": "9a0b1c2d-3e4f-5061-7283-94a5b6c7d8e9",
  "is_valid": true,
  "file_type": "video/mp4",
  "num_bytes": 4831785472,
  "file_status": "FILE_STATUS_INGESTED",
  "file_attributes": {
    "metadata_status": "not_extracted"
  },
  "ingested": true,
  "file_index": 2,
  "file_tags": {}
}

{
  "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"
    }
  ]
}

{
  "errors": [
    {
      "code": "file_not_found",
      "message": "No file with the given file_id was found for the organization.",
      "suggestion": "Verify the file_id and that the file has not been deleted.",
      "error_uid": "err-xxxxxxxx"
    }
  ]
}

Get Files Info List Files Metadata

⌘I

​Overview

​Path Parameters

​Response

Overview

Path Parameters

Response