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, prepaid top-up, and consented overage.

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)

  • Request body fields: camelCase (workflowKind, idempotencyKey, amountU)
  • Response body fields: camelCase (costU, balanceU, 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
{
  • "costU": 0,
  • "balanceU": 0,
  • "freeCredits": 0,
  • "sufficient": true,
  • "minFloorU": 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
quotedCostU
required
integer

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

consentedOverage
boolean
Default: false

Required when balance is insufficient and overage consent is active

inputsSummary
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "runId": "78c33d18-170c-44d3-a227-b3194f134f73",
  • "balanceAfterU": 0,
  • "chargedU": 0,
  • "overageTransactionId": "string"
}

Credits

Credit balance, ledger, top-up, consented overage

Current credit balance for the authenticated user

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "balanceMicroU": 0,
  • "balanceU": 0,
  • "periodEnd": "2019-08-24T14:15:22Z",
  • "lastGrantAt": "2019-08-24T14:15:22Z",
  • "freeTierMonthSpentMicroU": 0,
  • "overageConsentActive": true
}

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
amountU
required
integer [ 5000000 .. 500000000 ]

Top-up amount in µU. Default bounds $5–$500; configurable in topup_config.py.

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

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

Responses

Request samples

Content type
application/json
{
  • "amountU": 5000000,
  • "currency": "USD"
}

Response samples

Content type
application/json
{}

Toggle consented overage auto-charge for the active subscription period

Once enabled, over-balance commits in the current UsagePeriod synchronously call Paddle POST /subscriptions/{id}/charge before dispatching the workflow. Resets at next monthly rollover; user must re-consent each period.

Authorizations:
BearerAuth
Request Body schema: application/json
required
enable
required
boolean

Responses

Request samples

Content type
application/json
{
  • "enable": true
}

Response samples

Content type
application/json
{
  • "enabled": true,
  • "consentedAt": "2019-08-24T14:15:22Z",
  • "periodEnd": "2019-08-24T14:15:22Z"
}