Usage and billing
Examples use
$SPAVIK_BASE_URLand$SPAVIK_API_KEY, set in Get started.
POST /v1/billing/checkout
Subscribe to a plan (Stripe session)
Authentication : API key (X-API-Key) or web session (Authorization: Bearer)
Request body
| Name | Type | Description | |
|---|---|---|---|
plan | build | pro | growth | required |
Responses
| Code | Description |
|---|---|
200 | Success |
401 | Authentication required, or invalid token. |
403 | This caller is not allowed to perform this action. |
Example
curl -X POST "$SPAVIK_BASE_URL/v1/billing/checkout" \
-H 'X-API-Key: sk-spv-api-...' \
-H 'Content-Type: application/json' \
-d '{
"plan": "pro"
}'POST /v1/billing/credits
Top up your prediction balance
Buys a block of predictions at the plan rate (multiples of 100). The balance takes over once the monthly allowance is spent, so the API keeps answering instead of stopping mid-month. Returns a Stripe payment URL; the balance is credited when the payment settles, not when the request is made.
Authentication : API key (X-API-Key) or web session (Authorization: Bearer)
Request body
| Name | Type | Description | |
|---|---|---|---|
units | integer | required |
Responses
| Code | Description |
|---|---|
200 | Success |
401 | Authentication required, or invalid token. |
403 | This caller is not allowed to perform this action. |
409 | This plan has no unit price (Enterprise contract). |
Example
curl -X POST "$SPAVIK_BASE_URL/v1/billing/credits" \
-H 'X-API-Key: sk-spv-api-...' \
-H 'Content-Type: application/json' \
-d '{
"units": 1000
}'POST /v1/billing/portal
Open the Stripe billing portal
Authentication : API key (X-API-Key) or web session (Authorization: Bearer)
Responses
| Code | Description |
|---|---|
200 | Success |
400 | NO_BILLING_ACCOUNT: this account has never checked out, there is nothing to manage yet. |
401 | Authentication required, or invalid token. |
403 | This caller is not allowed to perform this action. |
Example
curl -X POST "$SPAVIK_BASE_URL/v1/billing/portal" \
-H 'X-API-Key: sk-spv-api-...'GET /v1/billing/subscription
Subscription and balance
Authentication : API key (X-API-Key) or web session (Authorization: Bearer)
Responses
| Code | Description |
|---|---|
200 | Success |
401 | Authentication required, or invalid token. |
403 | This caller is not allowed to perform this action. |
Example
curl -X GET "$SPAVIK_BASE_URL/v1/billing/subscription" \
-H 'X-API-Key: sk-spv-api-...'PATCH /v1/billing/subscription
Change plan
Authentication : API key (X-API-Key) or web session (Authorization: Bearer)
Request body
| Name | Type | Description | |
|---|---|---|---|
plan | build | pro | growth | required |
Responses
| Code | Description |
|---|---|
200 | Success |
401 | Authentication required, or invalid token. |
403 | This caller is not allowed to perform this action. |
409 | No active subscription. |
Example
curl -X PATCH "$SPAVIK_BASE_URL/v1/billing/subscription" \
-H 'X-API-Key: sk-spv-api-...' \
-H 'Content-Type: application/json' \
-d '{
"plan": "growth"
}'DELETE /v1/billing/subscription
Cancel at the end of the period
Authentication : API key (X-API-Key) or web session (Authorization: Bearer)
Responses
| Code | Description |
|---|---|
200 | Success |
401 | Authentication required, or invalid token. |
403 | This caller is not allowed to perform this action. |
409 | No active subscription. |
Example
curl -X DELETE "$SPAVIK_BASE_URL/v1/billing/subscription" \
-H 'X-API-Key: sk-spv-api-...'POST /v1/integrations/stripe/webhook
Incoming Stripe webhook
Called by Stripe, never by a client: the body is signed (Stripe-Signature) and verified on the raw bytes. One provider per route, each with its own signature and format. OUTGOING webhooks, the ones you register, live under /v1/webhooks.
Authentication : Public route, no authentication
Responses
| Code | Description |
|---|---|
200 | Success |
400 | Invalid signature. |
Example
curl -X POST "$SPAVIK_BASE_URL/v1/integrations/stripe/webhook" \
-H 'X-API-Key: sk-spv-api-...'GET /v1/plans
Public pricing
Authentication : Public route, no authentication
Responses
| Code | Description |
|---|---|
200 | Success |
Example
curl -X GET "$SPAVIK_BASE_URL/v1/plans" \
-H 'X-API-Key: sk-spv-api-...'GET /v1/requests
Request log (successful and failed calls)
Calls made by the active workspace, most recent first. status=error keeps only the failures: enough to look up a rejection that happened in production instead of reproducing it. Default window: 7 days (30 at most).
Authentication : API key (X-API-Key) or web session (Authorization: Bearer)
Parameters
| Name | In | Type | Description | |
|---|---|---|---|---|
from | query | string | optional | |
to | query | string | optional | |
status | query | all | error | optional | |
limit | query | integer | optional |
Responses
| Code | Description |
|---|---|
200 | Success |
401 | Authentication required, or invalid token. |
403 | This caller is not allowed to perform this action. |
503 | REQUEST_LOG_UNAVAILABLE: the request log (BigQuery) could not be read. |
Example
curl -X GET "$SPAVIK_BASE_URL/v1/requests" \
-H 'X-API-Key: sk-spv-api-...'GET /v1/usage
Account usage
Authentication : API key (X-API-Key) or web session (Authorization: Bearer)
Parameters
| Name | In | Type | Description | |
|---|---|---|---|---|
from | query | string | optional | |
to | query | string | optional | |
workspace_id | query | string | optional |
Responses
| Code | Description |
|---|---|
200 | Success |
401 | Authentication required, or invalid token. |
403 | This caller is not allowed to perform this action. |
503 | USAGE_UNAVAILABLE: the usage log (BigQuery) could not be read. |
Example
curl -X GET "$SPAVIK_BASE_URL/v1/usage" \
-H 'X-API-Key: sk-spv-api-...'