Core Concepts

Our API offers two main resource types: file and job. The idea is that you create one or more files, and then perform one or more jobs on them. A completed job also exposes its output as a file resource. This makes it possible to chain jobs together.

The API is not intended to be used for persistent storage. While we currently store all resources for about six months, this might change in the future without prior notice. Both files and jobs therefore have an expires_at field, which indicates the approximate date and time when they are scheduled for deletion.

Security

Never, under any circumstances, expose your client_id, client_secret or access token to end users of your application, and do not check them into version control. It is your responsibility to keep your credentials stored safely. You will be charged for operations performed by malicious users if your credentials were not stored appropriately.

Resource Management

We recommended that you only create a file if you already know that it's going to be used as input to a job afterwards. We also recommend downloading the output of a job to your system after processing. Relying on the API to permanently store resources for you is not a supported use case.

If you are building a customer-facing application, however, it's fine to await certain user actions. For example, if a user generates a master preview, you can provide them with a direct link to the public stream output of the job, and only transfer the full resolution master file to your system if the user completes a checkout process.

Performance Optimization

All endpoint responses for retrieving resources are cached. This means that the returned state of a resource in a response may at times be outdated. For time-critical applications, we therefore recommend setting up webhooks. Webhook notifications are dispatched immediately whenever the state of a resource changes meaningfully, and they contain the full up-to-date resource representation.

Jobs have an eta field which represents the estimated timestamp at which the system assumes the job to be done processing. While it is best practice to wait for a webhook notification for a completed job, you may need to manually poll for job updates in some scenarios. In those cases, we recommend to only start polling from the eta date and time and not earlier, because it is unlikely the job will be completed before then.