API Reference

Introduction

The Convilyn API lets you programmatically run any of the platform's nearly 100 AI workflows. The API is RESTful, uses Bearer token authentication, and returns JSON. This reference covers the complete job lifecycle from file upload to result download.

The Goal Lane API follows a request-reply pattern with optional interactive checkpoints. You create a job, fill any required slots, confirm to start execution, poll for status, handle mid-execution checkpoints if the workflow requires them, and download the result.

Base URL & Authentication

Base URL: https://api.convilyn.com/api/v1

Authorization: Bearer {your_api_key}
Content-Type: application/json

Step 1: Workflow Catalog

Start by fetching the available workflows to find the spec_id you need.

GET /workflows/catalog
Authorization: Bearer {token}

Returns an array of workflow catalog items. Each item includes:

Step 2: Upload a File

Upload the file(s) your workflow needs before creating the job. Use multipart/form-data encoding.

POST /upload
Authorization: Bearer {token}
Content-Type: multipart/form-data

file={binary}

Returns a file_id. Store it — you'll reference it when creating the job.

Step 3: Create a Job

POST /jobs/goal
Authorization: Bearer {token}
Content-Type: application/json

{
  "workflowId": "goal_lane.cover_letter",
  "fileIds": ["file_abc123", "file_def456"]
}

The response includes:

Step 4: Fill Required Slots

If the job response included slots, fill them before confirming. Skip this step if slots was empty.

PATCH /jobs/goal/{jobSpecId}/slots
Authorization: Bearer {token}
Content-Type: application/json

{
  "itemVersion": 1,
  "slots": [
    { "slotId": "tone", "value": "professional" },
    { "slotId": "length", "value": "one_page" }
  ]
}

The itemVersion field is required for all PATCH operations and implements optimistic locking. If two requests attempt to modify the same job simultaneously, the second will receive a 409 Conflict. A successful PATCH returns the updated job with an incremented itemVersion.

Step 5: Confirm & Start Execution

Once slots are filled (or immediately if there were none), confirm the job to begin asynchronous execution.

POST /jobs/goal/{jobSpecId}/confirm
Authorization: Bearer {token}
Content-Type: application/json

{ "itemVersion": 2 }

Returns 202 Accepted. Execution begins asynchronously. The job status transitions:

Step 6: Poll for Status

Example response while executing:

{
  "status": "executing",
  "progress": 45,
  "currentStep": "generating_output"
}

Full status lifecycle:

Poll every 2 seconds while executing. Stop when status is completed or failed. Do not poll more frequently — this will trigger rate limiting on the status endpoint.

On failed, the response includes an error field with a description of what went wrong.

Step 7: Interactive Checkpoints

Some workflows pause mid-execution and return to status: "slot_needed". This is expected — the workflow is waiting for your input before it can proceed.

When you receive slot_needed from the status endpoint:

{
  "status": "slot_needed",
  "checkpoint": {
    "checkpointId": "profile_review",
    "stepOutputPreview": "Detected roles: Senior Engineer, Tech Lead...",
    "slots": [
      { "slotId": "confirmed_titles", "type": "text" }
    ]
  },
  "itemVersion": 3
}

Present the stepOutputPreview and slot prompts to your user. Then fill the slot via PATCH /slots (using the current itemVersion), and confirm via POST /confirm to resume execution.

Workflows with multiple interactive phases cycle through:

Each checkpoint increments the itemVersion. Always use the latest version from the status response when submitting slots.

Step 8: Download Results

Once status is completed, request a pre-signed download URL.

{
  "url": "https://s3.amazonaws.com/convilyn-results/job_789/output.zip?X-Amz-...",
  "expiresAt": "2026-03-30T14:00:00Z",
  "filename": "output.zip"
}

Error Handling

The API uses standard HTTP status codes. Key error cases to handle:

Example: Handling a 409 Conflict

// Received 409 on PATCH /slots
// Re-fetch current job state
GET /jobs/goal/{jobSpecId}
// Response includes current itemVersion: 5

// Retry with correct version
PATCH /jobs/goal/{jobSpecId}/slots
{ "itemVersion": 5, "slots": [...] }

All error responses follow this shape:

{
  "error": "version_conflict",
  "message": "itemVersion mismatch: expected 5, got 3",
  "code": 409
}

Rate Limits

Rate limits apply per API key, per endpoint, and per plan tier. The X-RateLimit-Remaining and X-RateLimit-Reset headers are included in all responses to help you manage your consumption.

Full Flow Example

A minimal end-to-end flow for the cover letter workflow (no pre-execution slots, no interactive checkpoints):

// 1. Upload files
POST /upload  →  { "file_id": "file_resume123" }
POST /upload  →  { "file_id": "file_jd456" }

// 2. Create job
POST /jobs/goal
{
  "workflowId": "goal_lane.cover_letter",
  "fileIds": ["file_resume123", "file_jd456"]
}
→  { "jobSpecId": "job_789", "itemVersion": 1, "slots": [] }

// 3. Confirm immediately (no slots to fill)
POST /jobs/goal/job_789/confirm
{ "itemVersion": 1 }
→  202 Accepted

// 4. Poll until completed (every 2 seconds)
GET /jobs/goal/job_789/status  →  { "status": "executing", "progress": 30 }
GET /jobs/goal/job_789/status  →  { "status": "executing", "progress": 75 }
GET /jobs/goal/job_789/status  →  { "status": "completed" }

// 5. Download result
GET /jobs/goal/job_789/download
→  { "url": "https://s3.amazonaws.com/...", "expiresAt": "2026-03-30T14:00:00Z" }

For workflows with interactive checkpoints, the polling loop handles slot_needed responses by presenting the checkpoint data to your user, collecting their input, and cycling through PATCH + confirm before resuming the poll.