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.

A job works on your files where they're stored, so nothing is downloaded to do it. Name its type, the files in order, each once, and its settings. What it makes lands as new files beside the first one (a folder's zip beside the folder), or in the folder you name, never over them.

$ curl -X POST https://fffs.freakingfast.io/create-file-job \
  -H "Authorization: Bearer $SESSION" \
  -H "X-Absurd-App: fffd" \
  -H "Content-Type: application/json" \
  -d '{ "jobType": "cut", "fileIds": ["4f7c…"], "options": { "start": "1:20", "end": "2:05" } }'

It waits its turn, usually starting within half a minute when nothing's ahead of it. Ask /select-file-jobs how it's going, or watch /select-drive-events for its job event. Jobs count against your plan by the time they take: 1 hour a month on Intro, 4 hours a month on Basic, 15 hours a month on Pro. One that fails costs nothing, and /cancel-file-job stops one, keeping what it made. Send dryRun: true to check its settings and how long it should take without starting it.

Times are seconds, or a clock like 4:10. The OpenAPI spec has each setting's range.

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
}