SpectrAPI Documentation

SpectrAPI is a dataless API that generates realistic, structured data on demand. No database setup, no seed files, no infrastructure — just describe what you need in plain language and get production-quality data instantly.

Quickstart

Get your first response in under 30 seconds.

curl -X POST "https://api.spectrapi.com/api/v1/generate" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "Generate vehicle listings for Toyota cars",
    "count": 3
  }'

Authentication

All API requests require a Bearer token in the Authorization header. API keys are scoped to your account and can be managed from the dashboard.

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Base URL

All API requests should be made to the following base URL:

https://api.spectrapi.com/api/v1

All endpoints are served over HTTPS. HTTP requests will be redirected automatically.

Request Format

SpectrAPI uses a single POST endpoint that accepts JSON request bodies. Describe what you need in plain language using the instruction field.

Response Format

All responses follow a consistent envelope format with data and meta fields.

{
  "data": [
    {
      "id": "veh_a1b2c3d4",
      "make": "Toyota",
      "model": "Camry",
      "year": 2024,
      "trim": "SE",
      "price": 28945,
      "mileage": 12340,
      "color": "Celestial Silver"
    }
  ],
  "meta": {
    "request_id": "req_x7k9m2p4",
    "latency_ms": 47,
    "count": 1
  }
}

Meta Fields

Pagination

Control the number of items returned using the count parameter in your request body. You can request between 1 and 100 items per request.

curl -X POST "https://api.spectrapi.com/api/v1/generate" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "Generate vehicle listings",
    "count": 20
  }'

Category Rules

Category rules allow you to save and reuse output schemas across requests. When you provide a category_id, SpectrAPI will generate data matching your saved field names, types, and formatting rules.

Using Category Rules

Include the category_id parameter in your request to apply saved rules. The instruction still controls the content, but the structure follows your category definition.

curl -X POST "https://api.spectrapi.com/api/v1/generate" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "Generate electric vehicles",
    "category_id": "cat_vehicles_automotive",
    "count": 3
  }'

Benefits of Category Rules

Instruction Tips

Writing effective instructions helps SpectrAPI generate exactly the data you need. Here are best practices for crafting clear, precise instructions.

Be Specific

The more details you provide, the more accurate your data will be. Include specific values, ranges, or constraints.

Include Context

Describe the domain, use case, or scenario to help the API understand what kind of data relationships make sense.

Specify Data Types

Mention specific field types or formats you need, especially for dates, numbers, or structured data.

Use Natural Language

You don't need to use technical jargon or schema notation. Write instructions as you would explain them to a colleague.

{
  "instruction": "Generate a list of software engineers with 5+ years experience, including their name, email, phone number, current company, job title, programming languages they know, and years of experience. Make sure emails match the person's name and use common tech company domains."
}

Common Patterns

Error Codes

SpectrAPI uses standard HTTP status codes. Errors include a machine-readable code and a human-readable message.

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "status": 401
  }
}

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1709683200
Retry-After: 30

Rate Limits

Rate limits vary by plan and are enforced per API key.

SDKs & Libraries

Official client libraries to integrate SpectrAPI into your application with type safety and convenience methods.

import { SpectrAPI } from "spectrapi";

const spectr = new SpectrAPI("sk_live_your_api_key");

const data = await spectr.generate({
  instruction: "Generate Tesla vehicle listings",
  count: 10,
});

from spectrapi import SpectrAPI

client = SpectrAPI("sk_live_your_api_key")

data = client.generate(
    instruction="Generate Tesla vehicle listings",
    count=10,
)