Skip to main content

API Integration

API Integration​

The Komashi API lets you query and manage platform data programmatically. Use it to connect Komashi to your own systems, dashboards, or workflows.

The complete, always-current reference (OpenAPI 3.0) is published on your own instance. Open Settings → API / MCP in the Control Center and follow the Documentation link to the interactive API docs.

Authentication​

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Generate and manage API keys in Settings → API / MCP in the Control Center — there is no separate developer dashboard. Each key is a provider token scoped to your provider, with the Create / Read / Update / Delete permissions you assign when creating it. See API Tokens for details.

Base URL​

The API is served from your own Komashi instance under the /v1 prefix:

https://<your-instance>/v1

There is no shared api.komashi.com domain — replace <your-instance> with the host of your Control Center.

Key Endpoints​

MethodEndpointDescription
GET/v1/servicesList your services.
GET/v1/services/{service_id}/subscriptionsList subscriptions for a service.
GET/v1/customersRetrieve customer records.
POST/v1/customersCreate a new customer.
GET/v1/invoicesRetrieve invoice history.

The API also covers Plans, Periods, Prices, Add-ons and Add-on Options, Customer Contacts, Discounts, Payment methods, Invoice methods, subscription checkout / payment-link / change-plan / usage / quota, and magic-URL generation. See the Documentation link in Settings → API / MCP for the full endpoint list and request/response schemas.

Response Format​

All responses are returned as JSON, wrapped in the same envelope:

{
  "succeeded": true,
  "status_code": 200,
  "data": { }
}
  • succeeded — true for 2xx and 3xx statuses, false otherwise.
  • status_code — the HTTP status repeated in the body.
  • data — the payload. Read this field rather than the top level.

Two things to know:

  • A 204 No Content is returned to you as a 200 carrying the envelope.
  • There is no error field. On failure, check succeeded and status_code; the endpoint's own fields (for example message) travel alongside them.

Rate Limits​

The API allows 100 requests per minute per API key. Requests without a key are counted per IP address.

Exceeding the limit returns a 429 with error_code: RATE_LIMIT. Implement exponential backoff in your client.

What You Do NOT Need to Handle​

  • Subscription lifecycle — handled server-side.
  • Pricing logic — configured by providers, readable via API.

For full endpoint documentation, request/response schemas, and code examples, use the Documentation link in Settings → API / MCP.