Specifier API Documentation

Essential API reference for integrating with Specifier's intelligent data mapping platform.

Rate Limits

Rate limits vary by subscription tier. Monitor your usage via response headers and upgrade as needed.

Free Tier

  • Transformations/month:250
  • API requests/minute:10
  • Active mappings:Unlimited

Pro Tier

  • Transformations/month:2,500
  • API requests/minute:100
  • Active mappings:Unlimited

Enterprise

  • Transformations/month:Unlimited
  • API requests/minute:Unlimited
  • Active mappings:Unlimited

Response Headers

All transformation API responses include rate limit and usage information in headers.

API Rate Limits (Per Minute)

These headers track how many API requests you can make per minute.

X-RateLimit-Limit:10 (requests/min for your tier)
X-RateLimit-Remaining:8 (remaining this minute)
X-RateLimit-Reset:1642694460 (unix timestamp)

Monthly Transformation Limits

These headers track your monthly transformation quota usage.

X-Monthly-Limit:250 (transformations/month for your tier)
X-Monthly-Remaining:175 (remaining this month)
X-Monthly-Used:75 (used this month)
X-Monthly-Reset:1645372800 (unix timestamp)

Authentication

Specifier uses JWT tokens for authentication. Provide your login credentials for the JWT and use it in the Authorization header for all subsequent requests.

Get JWT Token

Get a JWT token for API access using your credentials.

POST /api/auth/token

Example Request

curl -X POST https://api.specifier.io/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'
const response =await fetch('https://api.specifier.io/api/auth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'your-password'
  })
});

const data= awaitresponse.json();
using varclient =new HttpClient();

var payload= new{
  email = "user@example.com",
  password = "your-password"
};

var json= JsonSerializer.Serialize(payload);
var content= newStringContent(json, Encoding.UTF8, "application/json");

var response =await client.PostAsync("https://api.specifier.io/api/auth/token", content);

Response

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5...",
  "user": {
    "_id": "6880029570674a3027ca3449",
    "email": "mark@specifier.io",
    "name": "Mark",
    "isVerified": true,
    "createdAt": "2025-07-22T21:28:53.302Z",
    "__v": 0
  }
}

Using the JWT Token

Include the JWT token in the Authorization header for all API requests.

curl -X GET https://api.specifier.io/api/mappings \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

Mapping Configuration

Retrieve your mapping configuration to understand field mappings and transformation rules before calling the transform endpoint.

Get Mapping Configuration

Retrieve detailed mapping configuration including field mappings and confidence scores.

GET /api/mappings/{mapping_id}

Example Request

curl -X GET https://api.specifier.io/api/mappings/mapping_abc123\
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"
const response= awaitfetch('https://api.specifier.io/api/mappings/mapping_abc123', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json'
  }
});

const data= awaitresponse.json();
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization=
  new AuthenticationHeaderValue("Bearer", "YOUR_JWT_TOKEN");

var response= awaitclient.GetAsync("https://api.specifier.io/api/mappings/mapping_abc123");
var content= awaitresponse.Content.ReadAsStringAsync();

Response

[
  {
    "_id": "68800db9670d6f6efe2d1c36",
    "name": "A to B",
    "source": {
      "type": "json",
      "name": "Sample JSON",
      "content": "{\n \"firstName\": \"John\",\n \"lastName\": \"Doe\", \n \"email\": \"john@example.com\",\n \"age\": 30,\n \"isActive\": true\n}"
    },
    "target": {
      "type": "file",
      "name": "API Spec",
      "url": "",
      "extractedFields": null
    },
    "status": "Draft",
    "confidence": 95,
    "createdAt": "2025-07-22T22:16:25.461Z",
    "updatedAt": "2025-07-23T07:37:56.630Z"
  }
]

Transform Endpoint

Use the transform endpoint to convert data from your source schema to your target schema in real-time.

Transform Data

Send data to transform it according to your mapping configuration.

POST /api/transform/{mapping_id}

Example Request

curl -X POST https://api.specifier.io/api/transform/mapping_abc123\
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceData": {
      "email":"john@example.com",
      "first_name": "John",
      "last_name":"Doe",
      "phone":"+1-555-123-4567"
    }
  }'
const response =await fetch('https://api.specifier.io/api/transform/mapping_abc123', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sourceData: {
      email: 'john@example.com',
      first_name:'John',
      last_name:'Doe',
      phone: '+1-555-123-4567'
    }
  })
});
using varclient =new HttpClient();
client.DefaultRequestHeaders.Authorization =
  new AuthenticationHeaderValue("Bearer","YOUR_JWT_TOKEN");

var payload= new{
  sourceData = new{
    email = "john@example.com",
    first_name = "John",
    last_name = "Doe",
    phone = "+1-555-123-4567"
  }
};

var json= JsonSerializer.Serialize(payload);
var content= newStringContent(json, Encoding.UTF8, "application/json");
var response =await client.PostAsync("https://api.specifier.io/api/transform/mapping_abc123", content);

Response

{
  "success": true,
  "transformedData": {
    "forename": "John",
    "surname": "Doe",
    "emailAddress": "john@example.com"
  },
  "mappingInfo": {
    "id": "68800db9670d6f6efe2d1c36",
    "name": "A to B",
    "confidence": 95
  }
}

Error Responses

When transformation fails, you'll receive detailed error information:

{
  "success": false,
  "error": {
    "code": "transformation_failed",
    "message": "Required field 'customer.email' is missing",
    "field": "customer.email"
  }
}