DevelopersHow to connect an assistantKeys
Reference/Files/Create

Upload a file directly

POSThttps://api.getwerk.ai/api/v1/assets

Uploads one photo, document or voice recording as its bytes, for a card, a project, the key's person's photo or a report to use.

Its kind follows Content-Type: a JPEG is a photo, a document's type or Werk-Filename a document, an audio type a recording. An upload not used within 24 hours is let go.

Authorization

AuthorizationheaderRequired

Authorization: Bearer <key> Authentication

Headers

Werk-Localestring

The language tag Werk writes the answer's own words in, such as step names and history lines, matched to a language it serves; a card's text stays as written. At a project's paths, the reads of its cards and steps, of a card, its update photos, a file and its reminders, and of follow and reminder invitations, and a document's read-now and consent, take the language of the person's chat with Werk in that project first, while it has one. Without either, the language Werk uses with the person the key or the connection acts for.

Idempotency-Keystring, uuidRequired

An id the caller makes for this request; sent again with it and the same bytes, it changes nothing twice.

Werk-Filenamestring

A document's name, percent-encoded.

Query parameters

projectenum or string, uuid

The project the upload is for.

Allowed values
purposeenum

profile_photo for the key's person's photo, account_feedback for a report's recording; it takes no project.

Allowed valuesaccount_feedbackprofile_photo

Body

image/jpegaudio/mp4audio/x-m4aaudio/webmaudio/oggapplication/pdfapplication/vnd.openxmlformats-officedocument.wordprocessingml.documentapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheettext/csvtext/plaintext/markdown

Response

201 The upload.

idstring, uuid

The file's id.

kindenum

What the file is: a photo, a voice recording or a document.

Allowed valuesimageaudiodocument
filenamestring

The document's name; only a document has one.

From 1 to 255 characters
formatenum

The document's format; only a document has one.

Allowed valuespdfdocxxlsxcsvtxtmd
mimeTypestring

The file's media type.

At least 1 character
sizeBytesinteger

The file's size in bytes.

At least 0
widthinteger

The photo's width in pixels; absent on photos stored before sizes were kept.

At least 1
heightinteger

The photo's height in pixels; absent on photos stored before sizes were kept.

At least 1
durationSecondsnumber

The recording's length in seconds; only a voice recording has one.

More than 0, up to 300
availableboolean

False once the file's bytes were released and it can no longer be read.

Errors

400invalid_queryThe query is not in the form the route takes; the limit is in the unit of the input details.field names (characters for a text, entries for a list, the value for a number).
400invalid_idempotency_keyThe Idempotency-Key header is not a uuid.
400conversation_requiredThe request names no project, and the session has no project of its own to use.
400invalid_mediaThe file, its name or the request about it is not in a form the route takes; the limit is in the unit of the input details.field names (characters for a text, entries for a list, the value for a number).
400photo_side_too_largeThe photo's longer side has more pixels than this request takes.
400unsupported_media_typeThe file's type is not one the route takes.
400document_unsupported_formatThe document's format is not one Werk reads.
400document_password_protectedThe document is protected by a password.
400document_unreadableThe document could not be read.
401session_revokedThe request carries no session the server holds, or its session has ended.
401session_expiredThe session has expired.
403not_for_clientThe route, setting or input the request names is open only to Werk's own apps, and the request's session is a connected app's or an API key's.
404conversation_not_foundThe project the request names, or its chat, is not one the signed-in person is in.
409session_changedThe session changed while the request was in flight.
409project_deletedThe project is being deleted.
409idempotency_conflictThe request's key, or the upload address it was sent to, was already used with other content.
413payload_too_largeThe request body has more bytes than the route takes.
413document_too_largeThe document has more bytes than Werk reads.
rate_limitedMore requests of this kind were sent than Werk takes within the time it counts them over.
500server_errorThe server could not complete the request, and it is not known whether a write it holds was made.
curl
curl -X POST "https://api.getwerk.ai/api/v1/assets?project=2f6c9e41-7a3b-4d58-9c1e-0b8d4f2a6e73" \
  -H "Authorization: Bearer wk_key_..." \
  -H "Idempotency-Key: f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4e03" \
  -H "Content-Type: image/jpeg" \
  --data-binary @file
TypeScript
import { readFile } from "node:fs/promises";

const res = await fetch("https://api.getwerk.ai/api/v1/assets?project=2f6c9e41-7a3b-4d58-9c1e-0b8d4f2a6e73", {
  method: "POST",
  headers: {
    Authorization: "Bearer wk_key_...",
    "Idempotency-Key": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4e03",
    "Content-Type": "image/jpeg",
  },
  body: await readFile("file"),
});
const answer = await res.json();
201JSON
{
  "id": "f3a9c1e7-5b2d-4c68-a4e0-9d7b3f1c5e82",
  "kind": "image",
  "mimeType": "image/jpeg",
  "sizeBytes": 482113,
  "width": 1600,
  "height": 1200
}