API Reference

Blindstrader exposes a RESTful API for each microservice. All APIs are documented using the OpenAPI 3.1 standard and rendered with the Scalar interactive UI.

Interactive API Reference

Open the full interactive API Reference (all services in one view):

Open API Reference →

For local development: http://docs.blindstrader.test/api-reference/

Per-Service API Docs

Each service also exposes its own API documentation directly:

Service	API Docs URL
Identity	https://identity.blindstrader.com/docs/api
Brand	https://brand.blindstrader.com/docs/api
Supplier	https://supplier.blindstrader.com/docs/api
Supply Chain	https://sc.blindstrader.com/docs/api
Payment	https://payment.blindstrader.com/docs/api
Retailer	https://retailer.blindstrader.com/docs/api
Platform	https://platform.blindstrader.com/docs/api
Notification	https://notification.blindstrader.com/docs/api

The unified portal at docs.blindstrader.com/api-reference/ aggregates all OpenAPI specs into a single Scalar view.

Authentication

All API endpoints (except public auth routes) require a Bearer token issued by the Identity Service.

Obtaining a Token

POST https://identity.blindstrader.com/api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}

Response:

{
  "token": "eyJ...",
  "expires_at": "2025-06-08T10:00:00Z"
}

Include the token in all subsequent requests:

Authorization: Bearer eyJ...

Token Scopes

Tokens carry RBAC claims enforced by the Identity Service. Attempting to access a resource your account is not permitted to access returns 403 Forbidden.

Common Response Formats

Success

{
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 150
  }
}

Error

{
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is required."]
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
204	No content (e.g. delete)
400	Bad request
401	Unauthenticated
403	Forbidden
404	Not found
422	Validation error
429	Rate limit exceeded
500	Server error

Rate Limiting

API calls are rate-limited per token:

Tier	Limit
Default	60 requests / minute
Premium	300 requests / minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 54
X-RateLimit-Reset: 1717839000

OpenAPI Spec Downloads

Raw OpenAPI JSON specs are available for download and use in Postman or code generation:

Service	Spec URL
Identity	https://docs.blindstrader.com/openapi/identity.json
Brand	https://docs.blindstrader.com/openapi/brand.json
Supplier	https://docs.blindstrader.com/openapi/supplier.json
Supply Chain	https://docs.blindstrader.com/openapi/supply-chain.json
Payment	https://docs.blindstrader.com/openapi/payment.json
Retailer	https://docs.blindstrader.com/openapi/retailer.json
Platform	https://docs.blindstrader.com/openapi/platform.json
Notification	https://docs.blindstrader.com/openapi/notification.json