API docs by Redocly

Convilyn Credits & Workflow Billing API (0.1.0-draft)

Download OpenAPI specification:

Convilyn Engineering: eng@convilyn.com

Credit-based dynamic pricing surface for Convilyn (pricing v2).

Scope

  • Workflow pre-flight quote + atomic commit (replaces existing forge quote/commit semantics with a workflow-agnostic shape; forge endpoints stay in payment_openapi.yaml for backwards compatibility during transition).
  • Credit balance, ledger history, and prepaid top-up.

Pricing model

See docs/business/pricing/pricing-v2.md for rates and the three-layer raw → insured → charged cost stack. Engineering contract: backend-api/docs/pricing/PRICING_CONTRACT.md. Paddle integration specifics: backend-api/docs/pricing/PADDLE_TOPUP_NOTES.md.

Naming convention (matches payment_openapi.yaml)

  • Units: credits are the single billing currency (1 credit = $0.01). No µU on the wire.
  • Request body fields: camelCase (workflowKind, idempotencyKey, amountCredits)
  • Response body fields: camelCase (costCredits, balanceCredits, freeCredits, sufficient)
  • Path / query params: snake_case
  • Idempotency: Idempotency-Key header on /workflow/commit and /credits/topup

Authentication

All endpoints require Bearer token authentication.

Workflow

Workflow-agnostic quote/commit replacing per-runner billing

Pre-flight cost quote for a workflow run

Authorizations:
BearerAuth
Request Body schema: application/json
required
workflowKind
required
string (WorkflowKind)
Enum: "goal_lane" "conversion" "forge"
specId
required
string
inputsSummary
object

Optional hints that improve quote accuracy without revealing PII — file_size_bytes, expected_token_count, expected_megapixels, expected_minutes_audio, etc. Server may ignore unknown fields.

Responses

Request samples

Content type
application/json
{
  • "workflowKind": "goal_lane",
  • "specId": "goal_lane.business_report_summary",
  • "inputsSummary": { }
}

Response samples

Content type
application/json
{
  • "costCredits": 0,
  • "balanceCredits": 0,
  • "freeCredits": 0,
  • "sufficient": true,
  • "minFloorCredits": 0,
  • "topUp": {
    }
}

Atomic credit deduction + workflow dispatch (idempotent)

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Caller-generated opaque key (8–128 chars; SHOULD be a UUIDv4). Replays return the original run_id without re-debiting.

Request Body schema: application/json
required
workflowKind
required
string (WorkflowKind)
Enum: "goal_lane" "conversion" "forge"
specId
required
string
quotedCostCredits
required
integer

Echo of the quote's costCredits; server re-validates within 20% tolerance

inputsSummary
object

Responses

Request samples

Content type
application/json
{
  • "workflowKind": "goal_lane",
  • "specId": "string",
  • "quotedCostCredits": 0,
  • "inputsSummary": { }
}

Response samples

Content type
application/json
{
  • "runId": "78c33d18-170c-44d3-a227-b3194f134f73",
  • "balanceAfterCredits": 0,
  • "chargedCredits": 0
}

Credits

Credit balance, ledger, top-up

Current credit balance for the authenticated user

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "balanceCredits": 0,
  • "periodEnd": "2019-08-24T14:15:22Z",
  • "lastGrantAt": "2019-08-24T14:15:22Z",
  • "freeTierMonthSpentCredits": 0
}

Paginated ledger of grants / deductions / top-ups

Authorizations:
BearerAuth
query Parameters
cursor
string
limit
integer <= 200
Default: 50
kind_filter
Array of strings (LedgerEntryKind)
Items Enum: "credit_grant_subscription" "credit_grant_trial" "credit_grant_promo" "credit_grant_free_monthly" "credit_deduction_workflow" "credit_topup" "credit_refund"

Responses

Response samples

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

Initiate a custom-amount one-time prepaid top-up via Paddle

Creates a Paddle non-catalog one-time transaction. Returns a Paddle checkout URL the frontend renders inline (CustomCheckout). Credits are added to the ledger only after transaction.completed webhook arrives — never before payment confirmation.

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
required
string [ 8 .. 128 ] characters

Caller-generated opaque key (8–128 chars; SHOULD be a UUIDv4). Replays return the original draft without re-creating it.

Request Body schema: application/json
required
amountCredits
required
integer [ 500 .. 50000 ]

Top-up amount in credits. Default bounds $5–$500 = 500–50,000 credits ($1 = 100 credits).

currency
string
Default: "USD"
Value: "USD"

USD-only at MVP (multi-currency in P8).

Responses

Request samples

Content type
application/json
{
  • "amountCredits": 500,
  • "currency": "USD"
}

Response samples

Content type
application/json
{}