resources

Upload a file

Send the file's bytes as the request body and its name in file_name. The body is the file itself, not multipart: it is streamed to storage without being held in memory, so Content-Length is required. Any Content-Type is accepted; the extension of file_name decides how the file is read. Reads PDF, Word, PowerPoint, Excel, OpenDocument, CSV, Markdown, HTML, text and images (scans and photos through OCR), up to 50 MB depending on the format (GET /v1/account lists the formats and their limits); a format Lookio does not read (.doc, .ppt, .odp, .rtf, .pages, .key, .epub, .zip, .heic) is refused with what to convert it to. By default the resource comes back queued and is read and indexed in the background (seconds for a short text, file or page, minutes for a site). Pass ?wait=true to wait up to 15 seconds for it to finish in one call, or poll GET /v1/resources/{id} (?wait=true works there too) until status is ready or failed. Importing costs no credits.

POST/v1/resources/file

Request

curl --fail-with-body --request POST \
  --url 'https://api.lookio.app/v1/resources/file?file_name=<file_name>' \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/octet-stream' \
  --data-binary '@document.xlsx'

import { readFile } from "node:fs/promises";

const response = await fetch("https://api.lookio.app/v1/resources/file?file_name=<file_name>", {
  method: "POST",
  headers: {
    "Authorization": "<api-key>",
    "Content-Type": "application/octet-stream"
  },
  body: await readFile("document.xlsx"),
  redirect: "error",
});
if (!response.ok) throw new Error(`Upload failed: ${response.status}`);
const data = await response.json();
console.log(data);

application/json

{
  "data": {
    "id": "res_thk6smb5nvts",
    "title": "Handbook",
    "type": "file",
    "status": "queued",
    "status_detail": null,
    "tags": [
      "hr"
    ],
    "source_url": null,
    "source": "Employee handbook, 2026 edition",
    "site": null,
    "created_at": "2026-10-12T09:30:00.000Z",
    "updated_at": "2026-10-12T09:30:00.000Z"
  },
  "request_id": "req_01K9X7M2Q4"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

Requires resources:write.

Send the file’s bytes as the request body, with a Content-Length header, and its name in the file_name query parameter. The body is the file itself, not multipart. The extension of the name decides how the file is read.

Terminalcurl "https://api.lookio.app/v1/resources/file?file_name=handbook.pdf&tags=hr" \
  -H "Authorization: Bearer $LOOKIO_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @handbook.pdf

Use --data-binary, not -d: -d alters the bytes. The body is streamed, never held in memory. tags is a comma-separated list.

Each format has its own size limit, from 5 MB for text to 50 MB for a PDF, and GET /v1/account lists the formats and their limits. An unsupported or legacy format is refused with invalid_parameter and advice on what to convert it to, and a file over its limit is refused with request_too_large. See File formats. An upload that ends before all its bytes arrive is refused and creates nothing.

The resource comes back queued. Importing is free. Poll Get a resource until it is ready or failed.

A retried upload with the same Idempotency-Key is recognised by its name, size and query, not by its bytes.

Authorizations

Authorizationbearerin headerrequired

Query parameters

file_namestringrequiredlength: 1–255 chars

The file's name with its extension, which decides how it is read (PDF, Word, Excel, CSV, images, Markdown, HTML…).

titlestringlength: 1–200 chars

Defaults to the file name without its extension.

tagsstringlength: ≤ 2000 chars

Comma-separated tags.

sourcestringlength: ≤ 500 chars

Where this resource comes from, shown with every citation of it: a URL or a mention such as "Employee handbook, 2026 edition". Up to 500 characters; an empty string clears it.

waitboolean | enum<string>

Wait up to 15 seconds for reading and indexing to finish before returning. Short texts, files and pages usually come back ready (or failed) in one call; larger imports return their current status (queued or processing) when the window ends, never an error.

Header parameters

Idempotency-Keystringlength: 1–255 chars

A unique key for this request, such as a UUID, 1 to 255 visible ASCII characters. Send the same key when you retry: the first response is returned (with Idempotent-Replayed: true) instead of running the request again, for 24 hours, per credential. The same key on a different request is a 409 conflict. A streamed answer is not recorded.

Body

application/octet-streamrequired

The file's bytes, unencoded. Content-Length is required.

The raw bytes of the file.

Response

application/json

Add a file

dataobjectrequired

Show child attributes

data.idstringrequiredpattern: ^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$

data.titlestringrequired

data.typeenum<string>requiredone of: text, file, url, site

data.statusenum<string>requiredone of: queued, processing, ready, failed, stale, ready_simulated

queued and processing: being read and indexed (pass wait=true or poll until it changes). ready: searchable. failed: see status_detail, then fix and call reindex.

data.status_detailstringnullrequired

data.tagsstring[]required

data.source_urlstringnullrequired

The page or site address, for url and site resources.

data.sourcestringnullrequired

Where it comes from, as shown with its citations.

data.siteobject | nullrequired

A site's page rules and schedule; null for other types.

Show child attributes

data.site.rulesobjectrequireddefault: {"include":[],"exclude":[],"excluded_urls":[]}

Show child attributes

data.site.rules.includestring[]requireddefault: []items: ≤ 50 items

Path patterns to keep, such as /docs/**. * is one level, ** everything below. Empty keeps the whole site.

data.site.rules.excludestring[]requireddefault: []items: ≤ 50 items

Path patterns to leave out, such as /blog/**.

data.site.rules.regexstringlength: ≤ 500 chars

Advanced: a regular expression on the path; matching pages are left out.

data.site.rules.excluded_urlsstring[]requireddefault: []items: ≤ 5000 items

Single pages to leave out, by full address.

manual syncs only on request. Recurring schedules accept daily, weekly, monthly, or every_N_days, every_N_weeks and every_N_months (1-90 days, 1-52 weeks, 1-12 months). Recurring schedules require a paid plan.

data.site.last_synced_atstringnullrequired

data.created_atstringrequired

data.updated_atstringrequired

request_idstringrequired

Upload a file

Authorizations

Query parameters

Header parameters

Body

Response

Use these docs with your AI tools

Query these docs via MCP

Query these docs over HTTP

Read these docs as Markdown