Skip to main content

​
Endpoints

MethodEndpointAuthPurpose
GET/api/agents/v1/subscriptions/plansBearer tokenList available subscription plans and pay-as-you-go options
GET/api/agents/v1/subscriptionsBearer tokenList user subscriptions (addon, enterprise, normal)
POST/api/agents/v1/subscriptionsBearer tokenCreate subscription — headless with payment_method_id or Checkout redirect
POST/api/agents/v1/subscriptions/confirm-checkoutBearer tokenConfirm a Stripe Checkout subscription session
GET/api/agents/v1/subscriptions/{id}/statusBearer tokenCheck subscription status
PUT/api/agents/v1/subscriptions/{id}Bearer tokenChange subscription plan
POST/api/agents/v1/subscriptions/{id}/pauseBearer tokenPause subscription
POST/api/agents/v1/subscriptions/{id}/resumeBearer tokenResume subscription
POST/api/agents/v1/subscriptions/{id}/reset-cycleBearer tokenReset billing cycle anchor

​
Discover available plans

Use this endpoint to list all subscription plans and learn about pay-as-you-go options before creating a subscription. 
curl --request GET 'https://modelslab.com/api/agents/v1/subscriptions/plans' \
  --header 'Authorization: Bearer <agent_access_token>' \
  --header 'Accept: application/json'
Response structure: 
{
  "data": {
    "subscription_plans": [
      {
        "id": 10,
        "name": "Basic Enterprise",
        "category": "enterprise",
        "period": "monthly",
        "type": "basic",
        "price": 249.0,
        "api_call_limit": 0,
        "rate_limit": 0,
        "features": ["Unlimited Images", "No Rate Limiter", "..."]
      }
    ],
    "pay_as_you_go": {
      "available": true,
      "description": "Pay only for what you use with wallet-based billing. No subscription required.",
      "minimum_topup_usd": 10.00,
      "currency": "USD",
      "auto_payments": {
        "supported": true,
        "description": "Automatically top up your wallet when balance drops below a threshold.",
        "configure_endpoint": "PUT /api/agents/v1/wallet/auto-funding",
        "disable_endpoint": "DELETE /api/agents/v1/wallet/auto-funding"
      },
      "fund_endpoint": "POST /api/agents/v1/wallet/fund"
    },
    "count": 37
  }
}
Use the id from a plan in subscription_plans as the plan_id when creating a subscription. Alternatively, use the pay-as-you-go option by funding your wallet directly. Create a subscription using a payment_method_id obtained from the Stripe API. No browser redirect needed. First, fetch the publishable key via GET /billing/stripe-config, then create a PaymentMethod via the Stripe API (see Headless Agent Flow for details): 
# Step 1: Fetch Stripe publishable key
STRIPE_PK=$(curl -s 'https://modelslab.com/api/agents/v1/billing/stripe-config' \
  -H 'Authorization: Bearer <agent_access_token>' | jq -r '.publishable_key')

# Step 2: Create PM via Stripe (card data stays with Stripe)
curl --request POST 'https://api.stripe.com/v1/payment_methods' \
  --user "$STRIPE_PK:" \
  --data 'type=card' \
  --data 'card[number]=4242424242424242' \
  --data 'card[exp_month]=12' \
  --data 'card[exp_year]=2027' \
  --data 'card[cvc]=123'

# Step 3: Subscribe with the pm_id
curl --request POST 'https://modelslab.com/api/agents/v1/subscriptions' \
  --header 'Authorization: Bearer <agent_access_token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: sub-plan10-20260220' \
  --data '{
    "plan_id": 10,
    "payment_method_id": "pm_1Xyz..."
  }'
Parameters:
  • plan_id (required, integer): The plan ID from the /subscriptions/plans endpoint
  • payment_method_id (optional, string): Stripe PM ID from the Stripe API. If omitted, falls back to Stripe Checkout redirect.
  • success_url / cancel_url (optional): Only used when payment_method_id is omitted (Checkout redirect flow).
Example response (headless): 
{
  "data": {
    "message": "Subscription created.",
    "subscription": {
      "id": 45,
      "plan_id": 10,
      "feature": "enterprise",
      "status": "active"
    },
    "stripe_subscription_id": "sub_xxx",
    "status": "active"
  },
  "error": null,
  "meta": {
    "request_id": "..."
  }
}
If the card requires 3D Secure, the response returns HTTP 402 with decline_code details. Cards requiring authentication should be handled via modelslab.com/pricing instead.

​
Confirm subscription checkout (Human-Assisted flow)

After a human completes a subscription payment via a Stripe Checkout URL (created with POST /billing/payment-link with purpose: "subscribe"), the agent confirms the session to activate the subscription. The human is redirected to ModelsLab’s success page after payment, where the session_id is displayed for them to copy and relay back to the agent. 
curl --request POST 'https://modelslab.com/api/agents/v1/subscriptions/confirm-checkout' \
  --header 'Authorization: Bearer <agent_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "session_id": "cs_live_..."
  }'
Parameters:
  • session_id (required, string): The Stripe Checkout session ID from POST /billing/payment-link response or copied by the human from the success page
If the payment hasn’t completed yet (human hasn’t finished checkout), poll this endpoint with a short delay. Once the session is confirmed, the subscription becomes active immediately.

​
Check subscription status

curl --request GET 'https://modelslab.com/api/agents/v1/subscriptions/45/status' \
  --header 'Authorization: Bearer <agent_access_token>'
Example response: 
{
  "data": {
    "id": 45,
    "plan_id": 10,
    "status": "active",
    "stripe_subscription_id": "sub_xxx",
    "current_period_start": "2026-02-20T00:00:00Z",
    "current_period_end": "2026-03-20T00:00:00Z"
  },
  "error": null,
  "meta": {
    "request_id": "..."
  }
}
Possible status values: active, past_due, canceled, paused, trialing.

​
Update subscription plan example

curl --request PUT 'https://modelslab.com/api/agents/v1/subscriptions/45' \
  --header 'Authorization: Bearer <agent_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{"new_plan_id": 456}'