API docs by Redocly

Convilyn Goal Mode API (1.0.0)

Download OpenAPI specification:

URL: https://convilyn.com/support License: Proprietary

Goal Mode API for intelligent multi-destination content processing.

Overview

Goal Mode lets users process files through predefined AI workflows.

User Flow

  1. Edit — User uploads files to the platform
  2. Select Workflow — User browses the workflow catalog and picks one
  3. Fill Slots — User answers required options/parameters for the workflow
  4. Download — System executes the pipeline; user downloads results

API Workflow (Primary: Workflow Selection)

  1. GET /workflows/catalog — Browse available workflows
  2. POST /jobs/goal — Create job with workflowId + fileIds (bypasses NLP)
  3. PATCH /jobs/goal/{jobSpecId}/slots — Fill pending slots (if any)
  4. POST /jobs/goal/{jobSpecId}/confirm — Confirm and start async execution
  5. GET /jobs/goal/{jobSpecId}/status — Poll for progress (or use the WebSocket stream)
  6. GET /jobs/goal/{jobSpecId}/download — Download results when completed

API Workflow (Alternative: Natural Language)

  1. POST /jobs/goal — Create job with goalText + fileIds (NLP resolves workflow)
  2. Steps 3-6 same as above

Key Features

  • Workflow Catalog: Browse and select workflows directly (no NLP needed)
  • Async Request-Reply: POST /confirm returns 202 Accepted, poll for status
  • Optimistic Locking: Use itemVersion to prevent concurrent modification conflicts
  • Smart Polling: Lightweight /status endpoint with adaptive intervals
  • Real-time Updates: WebSocket stream via x-websocket-events (replaces deprecated SSE path retired in Phase 7.4)
  • Interactive Checkpoints: Multi-phase workflows can pause mid-execution for user input

Interactive Checkpoint Workflows

Some workflows use pause_after checkpoints to pause execution mid-pipeline and collect user input before continuing. The flow is:

  1. Job enters EXECUTING state, pipeline runs until a checkpoint step completes
  2. WebSocket emits slot_needed with checkpointId and stepOutputPreview
  3. Frontend renders a checkpoint-specific UI (e.g., profile review, job selection)
  4. User submits slot answers via PATCH /slots
  5. Pipeline resumes from the next step

Example: resume_to_job_ready (3-phase interactive workflow)

  • Phase 1: Resume analysis → profile_review checkpoint (user confirms titles/skills)
  • Phase 2: Job discovery & scoring → job_selection checkpoint (user picks target jobs)
  • Phase 3: Tailored resume generation → download ZIP

Error Handling

  • 409 Conflict: Version mismatch (refresh and retry)
  • 422 Unprocessable: Validation errors
  • 400 Bad Request: Invalid state transitions

Audit

Read-only audit views (tool invocations, handoffs, specialist cost / reliability)

List persisted tool invocations for a job

Return every ToolUsageSample row written for this job, sorted chronologically by startedAt. Mirrors the live WebSocket tool_started / tool_finished stream so clients can re-hydrate the audit timeline after reconnection or for historical views.

Ownership: the authenticated user (or the anonymous session that submitted the job) is the only caller who can read the rows. Admins are NOT specially privileged via this endpoint — role- based admin read is deferred.

Cursor-paginated; the server enforces limit <= 200.

Authorizations:
BearerAuth
path Parameters
jobSpecId
required
string
Example: goal_abc123

Goal job specification ID (mirrored into runId on each row).

query Parameters
cursor
string

Opaque continuation token returned by a prior page's nextCursor.

limit
integer [ 1 .. 200 ]
Default: 50

Max rows per page (1-200, default 50).

specialistSpanId
string <uuid>

Filter to tool calls issued inside this specialist span only.

declared
boolean

Filter to only declared (true) or only extra (false) tools.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

List handoff records for a job

Return every HandoffRecord emitted during the run, in chronological order. Read from the live workflow checkpoint (MultiAgentEnvelope. handoff_history). Review-backlog consumers filter by reasonCode == "human_review_required" client-side.

Tier 3 minimum-viable observability; cross-job rollup ships in a later tier when handoff events denormalise onto the audit table.

Authorizations:
BearerAuthSessionCookie
path Parameters
jobSpecId
required
string

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List exception tickets for a job

Return every ExceptionTicket produced by the run, as stored on the live workflow checkpoint (MultiAgentEnvelope.exception_queue). Review surfaces group by severity from the taxonomy bundle; no cross-job rollup today.

Authorizations:
BearerAuthSessionCookie
path Parameters
jobSpecId
required
string

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Per-specialist cost rollup for a workflow

Aggregate ToolUsageSample.cost_micro_u per agent_role for every sample written against this workflow. Legacy rows with agent_role = null surface under the "unattributed" bucket. Authenticated owners only (404 on missing OR non-owner to avoid enumerating workflow ids).

Authorizations:
BearerAuth
path Parameters
workflowId
required
string

UserWorkflow id the caller owns.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Per-specialist outcome breakdown for a single run

Return one row per SpecialistOutcome persisted for this run, so the dashboard can reconstruct the delegation timeline (which specialist held, which escalated, how long each ran). runId is the Goal job spec id — authorization uses the same matrix as /audit/jobs/{id}/tool-invocations.

Authorizations:
BearerAuthSessionCookie
path Parameters
runId
required
string

Goal job spec id.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Per-specialist reliability + duration rollup for a workflow

Merge ToolUsageSampleRepository.failure_rates_by_specialist + avg_duration_by_specialist into one row per specialist so the dashboard renders a single list without a client-side join. Rows with only failure data (legacy samples without duration_ms) still appear with zeroed duration stats.

Authorizations:
BearerAuth
path Parameters
workflowId
required
string

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Events

Server-Sent Events for real-time updates

Goal Jobs

Goal Mode job operations

List User Workflow Sessions

List goal lane sessions for the authenticated user. Paginated, newest first. Requires authentication.

Authorizations:
BearerAuth
query Parameters
status
string (GoalJobStatus)
Enum: "draft" "created" "analyzing" "slots_pending" "ready" "ready_with_preview" "confirmed" "queued" "executing" "completed" "partial" "failed" "cancelled"

Filter sessions by job status

limit
integer [ 1 .. 50 ]
Default: 20

Maximum number of sessions to return (1-50)

cursor
string

Pagination cursor from previous response

Responses

Response samples

Content type
application/json
{
  • "sessions": [
    ],
  • "total": 0,
  • "nextCursor": "string"
}

Create Goal Job

Create a new Goal Mode job.

Primary flow (Workflow Selection): Provide workflowId from the catalog — bypasses NLP and routes directly to the selected workflow. This is the recommended path for the UI.

Alternative flow (Natural Language): Provide goalText — the system uses NLP to resolve the target workflow.

The system will:

  1. Route to the selected workflow (or resolve via NLP)
  2. Analyze input files for compatibility
  3. Generate any required slots for missing parameters
  4. Return the job with status and pending slots (if any)
Authorizations:
BearerAuth
Request Body schema: application/json
required
goalText
string [ 3 .. 2000 ] characters

Natural language goal description. Required when workflowId is not provided.

workflowId
string or null

Explicit workflow ID from the catalog. When provided, bypasses NLP resolution and routes directly to the workflow. Mutually exclusive with goalText and userWorkflowId.

userWorkflowId
string or null^uw_[a-zA-Z0-9_-]+$

User-authored workflow ID (from the User Workflows Builder). When provided, the server loads the UserWorkflow, compiles it to a DestinationSpec, and runs it through the same Goal Lane agent.

Contract guarantees (enforced by the compiler, not this endpoint):

  • requiredSlots is empty — the agent never pauses to ask the user
  • toolPalette excludes request_user_input
  • specId of the resulting job is user_<ownerPrefix>.<workflowId>

Mutually exclusive with goalText and workflowId.

fileIds
Array of strings
Default: []

List of uploaded file IDs to process. Required (minItems: 1) when workflowId is not provided. May be empty for workflow-based jobs that collect files via checkpoints.

Responses

Request samples

Content type
application/json
Example
{
  • "workflowId": "goal_lane.video_subtitle",
  • "fileIds": [
    ]
}

Response samples

Content type
application/json
{
  • "jobSpecId": "string",
  • "itemVersion": 0,
  • "attemptId": "6a4e12b7-3c5d-4f9a-a8d2-58b1c9a4a9d1",
  • "goalText": "string",
  • "fileIds": [
    ],
  • "status": "draft",
  • "progress": 100,
  • "resolvedDestinations": [
    ],
  • "pendingSlots": [
    ],
  • "filledSlots": { },
  • "pendingInterrupts": [
    ],
  • "preflightResult": {
    },
  • "tasks": [
    ],
  • "useCaseType": "video_subtitle",
  • "agentMessage": "string",
  • "errorMessage": "string",
  • "errorCode": "string",
  • "deliveryMode": "verified_pipeline",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "startedAt": "2019-08-24T14:15:22Z",
  • "completedAt": "2019-08-24T14:15:22Z",
  • "progressMessage": "string",
  • "artifacts": [
    ]
}

Get Workflow Usage Statistics

Get aggregated usage statistics for the authenticated user's workflow sessions. Returns totals by status, breakdowns by workflow type, and session counts by date.

Authorizations:
BearerAuth
query Parameters
from
string <date>
Example: from=2026-01-01

Start date filter (ISO format, inclusive)

to
string <date>
Example: to=2026-12-31

End date filter (ISO format, inclusive)

Responses

Response samples

Content type
application/json
{
  • "totalSessions": 0,
  • "completed": 0,
  • "failed": 0,
  • "cancelled": 0,
  • "byWorkflow": [
    ],
  • "byPeriod": [
    ]
}

Get Goal Job

Get the full current state of a Goal Mode job including pending slots, execution progress, tasks, and DAG steps.

For lightweight polling, use GET /jobs/goal/{jobSpecId}/status instead.

Authorizations:
BearerAuth
path Parameters
jobSpecId
required
string
Example: goal_abc123

Goal job specification ID

Responses

Response samples

Content type
application/json
{
  • "jobSpecId": "string",
  • "itemVersion": 0,
  • "attemptId": "6a4e12b7-3c5d-4f9a-a8d2-58b1c9a4a9d1",
  • "goalText": "string",
  • "fileIds": [
    ],
  • "status": "draft",
  • "progress": 100,
  • "resolvedDestinations": [
    ],
  • "pendingSlots": [
    ],
  • "filledSlots": { },
  • "pendingInterrupts": [
    ],
  • "preflightResult": {
    },
  • "tasks": [
    ],
  • "useCaseType": "video_subtitle",
  • "agentMessage": "string",
  • "errorMessage": "string",
  • "errorCode": "string",
  • "deliveryMode": "verified_pipeline",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "startedAt": "2019-08-24T14:15:22Z",
  • "completedAt": "2019-08-24T14:15:22Z",
  • "progressMessage": "string",
  • "artifacts": [
    ]
}

Delete Goal Job Session

Delete a goal job session. Only terminal sessions (completed, failed, cancelled, partial) can be deleted. Sessions that are currently executing or queued cannot be deleted.

Authorizations:
BearerAuth
path Parameters
jobSpecId
required
string
Example: goal_abc123

Goal job specification ID

Responses

Response samples

Content type
application/json
{
  • "error": "INVALID_REQUEST",
  • "message": "string",
  • "details": { }
}

Update Slots (drives **resume** semantic)

Fill pending slot values for a Goal Mode job.

This endpoint implements the resume continuation semantic (see docs/engineering/goal_lane_retry_semantics.md): the agent was paused at a HITL interrupt, the user answers, and the agent picks up from the exact step it paused at. Same job_spec_id, same attempt_id, same checkpoint.

Use this endpoint when:

  • Status is slots_pending or ready_with_preview.
  • pendingSlots or pendingInterrupts (P0-3 shape) is non-empty.

Do NOT use this endpoint for: retrying after failure (use /retry), or starting fresh (not supported — would return 501 on /retry with rerunMode=fresh_rerun).

Supports optimistic locking via expectedVersion field to prevent concurrent modification conflicts. If version mismatch occurs, returns 409 with current version.

Authorizations:
BearerAuth
path Parameters
jobSpecId
required
string
Example: goal_abc123

Goal job specification ID

Request Body schema: application/json
required
required
Array of objects (SlotAnswer) non-empty

List of slot answers

expectedVersion
integer or null

Expected item version for optimistic locking

Responses

Request samples

Content type
application/json
{
  • "answers": [
    ],
  • "expectedVersion": 3
}

Response samples

Content type
application/json
{
  • "jobSpecId": "string",
  • "itemVersion": 0,
  • "attemptId": "6a4e12b7-3c5d-4f9a-a8d2-58b1c9a4a9d1",
  • "goalText": "string",
  • "fileIds": [
    ],
  • "status": "draft",
  • "progress": 100,
  • "resolvedDestinations": [
    ],
  • "pendingSlots": [
    ],
  • "filledSlots": { },
  • "pendingInterrupts": [
    ],
  • "preflightResult": {
    },
  • "tasks": [
    ],
  • "useCaseType": "video_subtitle",
  • "agentMessage": "string",
  • "errorMessage": "string",
  • "errorCode": "string",
  • "deliveryMode": "verified_pipeline",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "startedAt": "2019-08-24T14:15:22Z",
  • "completedAt": "2019-08-24T14:15:22Z",
  • "progressMessage": "string",
  • "artifacts": [
    ]
}

Confirm and Execute

Confirm the goal job configuration and start asynchronous execution.

Returns 202 Accepted - execution happens asynchronously. Use the polling endpoint or the WebSocket stream to track progress.

Flow:

  1. Validates all required slots are filled
  2. Updates job status to QUEUED
  3. Sends message to SQS
  4. Returns immediately with 202

A background worker picks up the queued job and runs the workflow.

Prerequisites:

  • All required slots must be filled
  • Preflight validation must pass

Supports optimistic locking via expectedVersion field.

Authorizations:
BearerAuth
path Parameters
jobSpecId
required
string
Example: goal_abc123

Goal job specification ID

Request Body schema: application/json
optional
expectedVersion
integer or null

Expected item version for optimistic locking

Responses

Request samples

Content type
application/json
{
  • "expectedVersion": 5
}

Response samples

Content type
application/json
{
  • "jobSpecId": "goal_abc123",
  • "status": "queued",
  • "messageId": "msg_5f6e7d8c9b0a1",
  • "submittedAt": "2019-08-24T14:15:22Z",
  • "estimatedStartSeconds": 0,
  • "pollingUrl": "/api/v1/jobs/goal/goal_abc123/status",
  • "tasks": [
    ]
}

Retry Failed Job (drives **retry_same_thread** semantic)

Retry a failed goal job by resetting it to READY and re-queuing for execution. Do NOT call this for interrupt-resume — use PATCH /slots for that.

Client decision tree (see also docs/engineering/goal_lane_retry_semantics.md):

Job status Right endpoint rerunMode
slots_pending (user owes an answer) PATCH /slots n/a (always resume)
failed (agent errored) POST /retry retry_same_thread (default)
completed + user wants fresh start POST /retry with fresh_rerun returns 501 today
Any other status do not continue — check status first n/a

Only jobs with status failed can be retried. The endpoint:

  1. Validates ownership and FAILED status.
  2. Appends an AttemptRecord to the job's history and regenerates attempt_id (P0-4).
  3. Resets job to READY (clears error fields) — checkpoint is NOT deleted; next agent tick resumes from it.
  4. Queues for async execution.
  5. Returns 202 with polling URL.

rerunMode (P0-4 scaffold, optional body):

  • retry_same_thread (default): resume from the last checkpoint on the same job_spec_id / thread_id. Matches pre-P0-4 behaviour exactly.
  • resume: same transport as retry_same_thread today. Distinct name kept for the future taxonomy so clients can signal "I explicitly wanted the paused-mid-execution semantic" vs "I wanted to retry after failure". No server divergence today.
  • fresh_rerun: not implemented — returns 501. Product gaps (result retention, support runbook) must close first.
Authorizations:
BearerAuth
path Parameters
jobSpecId
required
string
Example: goal_abc123

Goal job specification ID

Request Body schema: application/json
optional
rerunMode
string
Default: "retry_same_thread"
Enum: "resume" "retry_same_thread" "fresh_rerun"

Which rerun semantic to apply. See docs/engineering/goal_lane_retry_semantics.md for the full resume / retry / rerun taxonomy.

reason
string or null <= 512 characters

Optional operator-supplied note (stored on the attempt audit record)

Responses

Request samples

Content type
application/json
{
  • "rerunMode": "resume",
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "jobSpecId": "goal_abc123",
  • "status": "queued",
  • "messageId": "msg_5f6e7d8c9b0a1",
  • "submittedAt": "2019-08-24T14:15:22Z",
  • "estimatedStartSeconds": 0,
  • "pollingUrl": "/api/v1/jobs/goal/goal_abc123/status",
  • "tasks": [
    ]
}

Download Results (Legacy) Deprecated

Get download URL for completed goal job results. Returns the primary artifact only.

Deprecated: Use GET /jobs/goal/{jobSpecId}/artifacts for multi-artifact support.

Only available when job status is COMPLETED or PARTIAL.

Authorizations:
BearerAuth
path Parameters
jobSpecId
required
string
Example: goal_abc123

Goal job specification ID

Responses

Response samples

Content type
application/json
{
  • "downloadUrl": "http://example.com",
  • "fileName": "string",
  • "sizeBytes": 0,
  • "mimeType": "string",
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Cancel Goal Job

Cancel a running or pending goal job.

Valid from states: draft, created, analyzing, slots_pending, ready, ready_with_preview, confirmed, queued, executing.

Terminal states (completed, partial, failed, cancelled) cannot be cancelled.

Authorizations:
BearerAuth
path Parameters
jobSpecId
required
string
Example: goal_abc123

Goal job specification ID

Responses

Response samples

Content type
application/json
{
  • "jobSpecId": "string",
  • "status": "cancelled"
}

List Artifacts

Get all output artifacts for a goal job with presigned download URLs.

Available when job status is COMPLETED or PARTIAL.

Authorizations:
BearerAuth
path Parameters
jobSpecId
required
string
Example: goal_abc123

Goal job specification ID

Responses

Response samples

Content type
application/json
{
  • "artifacts": [
    ],
  • "total": 0
}

Download Single Artifact

Get presigned download URL for a specific artifact.

Authorizations:
BearerAuth
path Parameters
jobSpecId
required
string
Example: goal_abc123

Goal job specification ID

artifactId
required
string

Artifact identifier

Responses

Response samples

Content type
application/json
{
  • "downloadUrl": "http://example.com",
  • "fileName": "string",
  • "sizeBytes": 0,
  • "mimeType": "string",
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Batch Download Artifacts

Download multiple artifacts as a ZIP file.

If artifactIds is empty or omitted, all artifacts are included. Server packages them into a ZIP and returns a presigned URL.

Authorizations:
BearerAuth
path Parameters
jobSpecId
required
string
Example: goal_abc123

Goal job specification ID

Request Body schema: application/json
optional
artifactIds
Array of strings

Artifact IDs to include in the ZIP. If empty or omitted, all artifacts are included.

Responses

Request samples

Content type
application/json
{
  • "artifactIds": [
    ]
}

Response samples

Content type
application/json
{
  • "downloadUrl": "http://example.com",
  • "fileName": "goal_abc123_artifacts.zip",
  • "sizeBytes": 0,
  • "mimeType": "application/zip",
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Polling

Lightweight status polling

Get lightweight job status (for polling)

Returns minimal status information for efficient polling.

Uses DynamoDB ProjectionExpression to minimize read costs. Response includes suggested polling interval based on job state.

Adaptive Polling:

  • QUEUED/EXECUTING: Poll every 1-2 seconds
  • Slow progress: Increase interval to 5-10 seconds
  • COMPLETED/FAILED/CANCELLED: No need to poll
Authorizations:
BearerAuth
path Parameters
jobSpecId
required
string
Example: goal_abc123

Goal job specification ID

Responses

Response samples

Content type
application/json
{
  • "jobSpecId": "goal_abc123",
  • "status": "draft",
  • "progress": 100,
  • "itemVersion": 0,
  • "attemptId": "string",
  • "tasksCompleted": 0,
  • "tasksFailed": 0,
  • "tasksTotal": 0,
  • "errorMessage": "string",
  • "progressMessage": "Analyzing resume structure...",
  • "agentMessage": "string",
  • "suggestedPollIntervalMs": 2000,
  • "deliveryMode": "verified_pipeline",
  • "pendingInterrupts": [
    ]
}

Workflows

Workflow catalog and discovery

Get Workflow Catalog

Returns a list of available workflows that users can select directly, bypassing the NLP-based destination resolution.

Each workflow includes metadata for UI display: name, description, supported input types/formats, and required slot count.

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "workflows": [
    ],
  • "total": 15
}