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

Requires version 1.1.5 or later of the Archetype platform.

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

string

required

Identifier of the file whose metadata to fetch

Response

string

Identifier of the file

string

Internal unique identifier of the file

boolean

Whether the metadata record is valid

string

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

integer

Size of the file in bytes

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

boolean

Whether the file has completed ingestion

integer

Index of this file within the organization’s file list

object

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

object

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

Show image attributes

integer

Image width in pixels

integer

Image height in pixels

integer

Number of color channels

array

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

Show tabular attributes

integer

Number of columns

array

Column header names

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

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

⌘I

​Overview

​Path Parameters

​Response

Overview

Path Parameters

Response