Quickstart

This walks you from zero to a generated handoff in three steps. You will need a Flow Relay account with at least one project and one connected integration.

1. Create an API key

Open Settings > API Keys in the dashboard and create a key. Keys are prefixed with fr_ and shown once at creation – copy it immediately and store it in a secret manager. You can revoke and re-create keys at any time.

2. List your projects

Every generation is scoped to a project, so grab a project_id first.

curl "https://www.flowrelay.it/api/v1/projects" \
  -H "Authorization: Bearer fr_your_api_key"

The response includes your tenant context and an array of accessible projects:

{
  "account_type": "business",
  "organizations": [{ "id": "8c2b1a90-1234-4abc-9def-0123456789ab", "name": "Acme", "slug": "acme", "role": "admin" }],
  "projects": [
    { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Payments", "project_type": "organization", "access_role": "admin" }
  ]
}

3. Generate a handoff

Handoff generation is asynchronous. You POST a request, receive a jobId, then poll until the job completes.

curl "https://www.flowrelay.it/api/v1/handoffs" \
  -H "Authorization: Bearer fr_your_api_key" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{ "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }'
{ "jobId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "status": "pending" }

Poll the job until status is completed:

curl "https://www.flowrelay.it/api/v1/jobs/c3d4e5f6-a7b8-9012-cdef-123456789012" \
  -H "Authorization: Bearer fr_your_api_key"
{
  "job": { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "status": "completed", "result_kind": "handoff", "result_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" },
  "result": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "title": "Checkout refactor handoff", "summary": "..." }
}

That is the whole loop: enqueue -> poll -> read the artifact. The same pattern powers insights.

Next steps

PreviousOverviewNext Authentication