The Convilyn 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: https://api.convilyn.com/api/v1. Authentication via Bearer token. All request bodies are JSON unless noted.

Step 1: Browse the 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 items. Each item includes:

  • spec_id — the identifier you'll use when creating a job (e.g., goal_lane.cover_letter)
  • name — human-readable workflow name
  • description — what the workflow does
  • supported_input_formats — accepted file types
  • required_slots — slots that must be filled before execution starts (may be empty)

Step 2: Upload a File

Upload the file(s) your workflow needs before creating the job.

POST /upload
Content-Type: multipart/form-data

file={binary}

Returns a file_id. Store it — you'll reference it when creating the job. Files expire after 24 hours if not associated with a 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:

  • jobSpecId — the job identifier used in all subsequent requests
  • status: "pending" — initial state
  • slots — an array of slot definitions if the workflow requires pre-execution input. Empty array if none.
  • itemVersion — the current version number, used for optimistic locking in subsequent requests

Step 4: Fill Required Slots (if any)

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" }
  ]
}

itemVersion is required for all PATCH operations. It prevents concurrent modification conflicts — if two requests try to modify the same job simultaneously, the second will receive a 409 Conflict. The response to a successful PATCH returns the updated job with an incremented itemVersion.

Step 5: Confirm and Start 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 from pending to confirming to executing.

Step 6: Poll for Status

GET /jobs/goal/{jobSpecId}/status
Authorization: Bearer {token}

Example response while executing:

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

Status lifecycle: pending → confirming → executing → completed | failed

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: Handle Interactive Checkpoints (SLOT_NEEDED)

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

When you receive slot_needed:

{
  "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 will cycle through executing → slot_needed → executing as many times as the workflow spec defines. Each checkpoint increments the itemVersion.

Step 8: Download Results

Once status is completed:

GET /jobs/goal/{jobSpecId}/download
Authorization: Bearer {token}

Returns a pre-signed download URL. The URL is valid for 1 hour. The output file itself (usually a ZIP containing all generated files) is retained for 24 hours after job completion.

Error Handling

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

  • 409 Conflict: itemVersion mismatch. Re-fetch the job to get the current itemVersion, then retry the operation with the correct value.
  • 422 Unprocessable Entity: Validation error. The response body includes an errors array with field-level details. Fix the request and retry.
  • 400 Bad Request: Invalid state transition — for example, attempting to confirm a job that is already executing, or filling slots on a completed job. Check your state machine logic.
  • 429 Too Many Requests: Rate limit hit. Back off and retry. Free tier limits are stricter than paid tiers.

Example 409 error flow:

// 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": [...] }

Rate Limits

Rate limits apply per API key, per endpoint, and per plan tier:

  • Free tier: 10 job creations per day, 60 status poll requests per minute
  • Paid tiers: Scale with plan — see your account dashboard for current limits

The X-RateLimit-Remaining and X-RateLimit-Reset headers are included in all responses to help you manage your consumption.

Full Flow: Cover Letter 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 (no slots to fill)
POST /jobs/goal/job_789/confirm
{ "itemVersion": 1 }
→  202 Accepted

// 4. Poll until completed
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
GET /jobs/goal/job_789/download  →  { url: "https://..." }

A Note on This Documentation

This is early SDK documentation — we iterate based on developer feedback. Endpoint paths and response shapes are stable, but we add capabilities regularly. If you're building on the API and run into anything unclear, reach out via the Convilyn community or developer forum. We want to know where the documentation doesn't match reality.