SynthosSynthos

API Reference

v1

Getting Started

The Synthos API lets you integrate AI training data validation directly into your ML pipeline. All API requests are made to https://api.synthos.dev and must include the appropriate headers.

Authentication Flow

  1. Create an account by calling POST /api/v1/auth/register with your email and password.
  2. Verify your email using the OTP code sent to your inbox via POST /api/v1/auth/verify-email.
  3. Get your token by calling POST /api/v1/auth/login. This returns a JWT valid for 24 hours.
  4. Include the token in all authenticated requests using the Authorization: Bearer YOUR_TOKEN header.

Base URL

https://api.synthos.dev/api/v1/

Request Headers

Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

API Key Authentication

For server-to-server integrations, you can also authenticate using an API key. Generate one from your dashboard settings. Pass it as X-API-Key: sk_live_... header.

Authentication

Register, login, and manage user accounts. All authenticated endpoints require a Bearer token.

Datasets

Upload, manage, and inspect training datasets. Uploads use signed URLs for secure, direct-to-storage transfers.

Validations

Create and monitor validation jobs. Validations analyze datasets for model collapse risk, quality issues, and training outcome prediction.

Warranties

Request and manage performance warranties on validated datasets. Warranties provide financial backing for prediction accuracy.

Credits

Manage your credit balance, purchase credits, and view transaction history. Credits are consumed when running validations.

Support

Create and manage support tickets. Our team typically responds within 4 business hours.

Rate Limits

Rate limits are applied per API key / token. Exceeding the limit returns a 429 status with a Retry-After header.

TierRequestsBurstNotes
Free60 / min10 / secDefault for new accounts
Pro300 / min30 / secPurchased credit package
Enterprise1,000 / min100 / secCustom agreement

Credit Costs

Each operation consumes credits from your balance. Purchase credits from the dashboard or via the API.

OperationCreditsDescription
Quick Scan10Basic quality check and row count verification
Standard Validation25Collapse detection + quality scoring
Comprehensive Validation50Full cascade validation with training prediction
Warranty Request100Performance warranty issuance

Error Codes

All errors return a JSON body with a message field describing the issue.

Error Response Format

{
  "error": {
    "code": 422,
    "message": "Validation failed: dataset_id is required.",
    "request_id": "req_abc123"
  }
}
CodeNameDescription
400Bad RequestThe request body is invalid or missing required fields.
401UnauthorizedMissing or invalid authentication token.
403ForbiddenYou do not have permission to access this resource.
404Not FoundThe requested resource does not exist.
409ConflictA resource with the same identifier already exists.
422Unprocessable EntityThe request was well-formed but contains semantic errors.
429Too Many RequestsRate limit exceeded. Retry after the Retry-After header value.
500Internal Server ErrorAn unexpected error occurred on our end.