Guides
Console
Start typing to search…

Sync and async execution

Use the standard HTTP Prefer header to control synchronous and asynchronous behavior across Picsart Creative APIs.

We are standardizing how clients control sync vs async behavior across Picsart Creative APIs.

Historically, some endpoints were synchronous, some were asynchronous, and some exposed a mode parameter to choose between the two. This worked, but it created an inconsistent developer experience and forced teams to learn different patterns per endpoint.

Going forward, we are implementing a single, standards-based approach at the API gateway layer using the HTTP Prefer header.

  • Endpoints are synchronous by default
  • You can explicitly request async behavior using Prefer
  • You can ask the gateway to wait for a bounded amount of time, and fall back to async without timing out

This change is rolling out first for task-based (pluggable) API operations, and will expand over time.

📘

Standard reference

This behavior follows RFC 7240: Prefer Header for HTTP, including the respond-async preference and the Preference-Applied response header.

RFC: https://datatracker.ietf.org/doc/html/rfc7240

How it works in Picsart

Default behavior

If you do not send a Prefer header, the endpoint runs in sync mode by default and returns:

  • 200 OK with the final result (if the operation completes within the normal synchronous request time limits)
🚧

Note: Some services are still transitioning. A few endpoints may remain async-first until the rollout is complete. See “Rollout status” below for guidance.

Force async responses

Send:

Prefer: respond-async

Result:

  • The request switches to async mode
  • The API responds with 202 Accepted
  • You receive an operation identifier using the endpoint’s existing async contract (for example a job id or task id), and you can retrieve the final result using the endpoint’s normal “get result” pattern

If the preference is applied, the response includes:

Preference-Applied: respond-async

Wait for a result, then fall back to async

Send either of the following:

  • Prefer: respond-async, wait=5
  • Prefer: wait=5

In our implementation, these two forms are treated the same.

Behavior:

  • The gateway waits up to N seconds for the result

  • During the wait period, it polls internally once per second

  • If the result is ready within the wait window, you get:

    • 200 OK with the final result

  • If the result is not ready, you get:

    • 202 Accepted with an operation identifier (same async contract as the endpoint already uses)

Constraints:

  • Supported wait values are 1 to 600 seconds
  • If wait is greater than 600, we cap it to 600
  • If wait is less than 1, we ignore the wait value

If the preference is applied, the response includes:

Preference-Applied: respond-async, wait=5

Response headers you should expect

Preference-Applied

When the server honors your preference, it returns:

Preference-Applied: respond-async or Preference-Applied: respond-async, wait=<seconds>

Use this as your confirmation that the gateway applied your request.

If you send Prefer and you do not see Preference-Applied, one of these is likely true:

  • The endpoint has not been migrated to support this behavior yet
  • The preference could not be applied for this request
  • The request was handled by a service path that does not use the new gateway behavior

Practical recommendations

If you want predictable latency

Use Prefer: respond-async.

This gives you a fast 202 Accepted response and avoids waiting on long operations.

If you want “best effort sync” without timeouts

Use Prefer: wait=<seconds>.

This is ideal when you want synchronous results most of the time, but you want a clean fallback to async for slower inputs.

If you are switching an async-first endpoint to sync

Use Prefer: wait=60.

A 60 second wait is a common default timeout for synchronous requests. This is the recommended migration path for endpoints that used to be async by default.

Deprecation notice: mode parameter

Some services expose a mode parameter (for example, sync vs async) to control execution behavior.

That parameter is now deprecated.

What to know:

  • Prefer header is the standard path going forward
  • If both mode and Prefer are provided, Prefer takes precedence
  • We recommend migrating now to avoid future breaking changes when mode is removed

Migration guide: mode parameter to Prefer header

Use these mappings:

If you currently use async mode

Before:

  • mode=async

After:

  • Prefer: respond-async

If you currently use sync mode

Before:

  • mode=sync

After:

  • Prefer: wait=60
📘

Tip: You can set wait lower than 60 if you want faster fallbacks to async. For example, Prefer: wait=10 is often a good UX tradeoff for interactive apps.

If you currently rely on “auto” behavior

Before:

  • mode=auto (or similar behavior)

After:

  • Use the default behavior (no Prefer) for sync-first
  • Or use Prefer: wait=<seconds> if you want bounded waiting with an async fallback

Rollout status and support

This capability is being introduced as a gateway-level standard and is rolling out incrementally. Not all services support it yet.

If you are unsure whether a specific endpoint supports Prefer, or you see missing Preference-Applied headers, please reach out via our Help Center:

https://support.picsart.com/hc/en-us

When you contact support, include:

  • The endpoint URL
  • The Prefer header you sent
  • The response status code and headers (especially Preference-Applied, if present)
  • Any request id headers your client captured (if available)

Updated about 3 hours ago