HTTP API

An API token doesn't call the file service itself. Trade it at /exchange-token for a session token, and send that as the bearer token, along with X-Absurd-App: fffd.

$ curl -X POST https://auth.freakingfast.io/exchange-token \
  -H "Authorization: Bearer $FREAKING_FAST_API_TOKEN"

{
  "gelToken": "eyJhbGciOiJIUzI1NiIs…",
  "expiresIn": 86400,
  "userId": "73ad9b0e-7227-11ef-9399-bfdd82c9e268"
}

The session lasts a day, as expiresIn says in seconds. Trade the token again before it runs out. Keep userId: new files go under users/{userId}/.

$ curl -X POST https://fffs.freakingfast.io/search-files \
  -H "Authorization: Bearer $SESSION" \
  -H "X-Absurd-App: fffd" \
  -H "Content-Type: application/json" \
  -d '{ "text": "harbor", "type": "Video" }'

Files go straight to storage on a signed form, so an upload never passes through the API.

1. Ask for a form

   POST/generate-file-urls

   typestringrequired

   The kind of file, like Video, Audio or Image.

   fileNamestringrequired

   The name it shows under.

   fileSizeintegerrequired

   Its exact size in bytes, up to 2 TB.

   objectKeystringrequired

   Where it is stored: users/{userId}/…

   mimeTypestring

   Its content type.

   You get an uploadUrl and an uploadForm. The form lasts 2 days.

2. Send the file

   POST the file to uploadUrl as multipart/form-data, with every uploadForm field before it, unchanged.

3. Record it

   POST/insert-file

   Send the same fields with isPublic: false and creator: { id: userId }. The service reads the stored size back, and turns the file down if it differs from fileSize. You get the new file's id.

Above 64 MiB, send a file in parts instead, many at once. If an upload stops, start it again with the same objectKey and only the missing parts go up.

/generate-download-url gives a link to any of your files that lasts 6 hours. /toggle-file-access makes a file public, and its link then stays up for good, played from the closest region.

Every route is a POST to https://fffs.freakingfast.io with a JSON body. The OpenAPI spec has the full request and response for each.

Errors come back with a sentence for people and a code for code. retryable says whether trying again could work, which the status alone doesn't tell you.

{
  "error": "A fileSize is required",
  "code": "missing_field",
  "field": "fileSize",
  "retryable": false
}