Making API Requests

This guide explains how to make requests to the SynthesQ API, including request structure, headers, parameters, and response formats.

Base URL

All API requests should be made to:

https://api.synthesq.com/api/v1

API versioning is managed via the URL path (/v1). This ensures backward compatibility as new versions are released.

Request Structure

HTTP Methods

The API uses standard HTTP methods:

• GET - Retrieve resources
• POST - Create new resources
• PUT / PATCH - Update existing resources
• DELETE - Remove resources

Required Headers

Every API request must include these headers:

Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

Example Request:

curl https://api.synthesq.com/api/v1/operations/products \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1..." \
  -H "Accept: application/json"

Request Parameters

URL Parameters

URL parameters are used for resource identification:

# Get specific product by ID
GET /api/v1/operations/products/{id}

# Example
GET /api/v1/operations/products/123

Query Parameters

Query parameters are used for filtering, sorting, and pagination:

# Filter products by status
GET /api/v1/operations/products?status=active

# Multiple filters
GET /api/v1/operations/products?status=active&type=simple&category_id=5

# Pagination
GET /api/v1/operations/products?page=2&per_page=25

# Sorting
GET /api/v1/operations/products?sort=-created_at

Sorting:

• Prefix with - for descending order: ?sort=-name
• No prefix for ascending order: ?sort=name
• Multiple sort fields: ?sort=status,-created_at

Request Body (POST/PUT/PATCH)

For creating or updating resources, send data in the request body as JSON:

curl -X POST https://api.synthesq.com/api/v1/operations/products \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Premium Laptop",
    "sku": "LAPTOP-001",
    "type": "simple",
    "selling_price": 1299.99,
    "cost_price": 899.00,
    "stock_quantity": 50,
    "category_id": 3,
    "supplier_id": 12
  }'

Response Format

Successful Responses

All successful responses return JSON with a consistent structure:

Single Resource:

{
  "data": {
    "id": 123,
    "name": "Premium Laptop",
    "sku": "LAPTOP-001",
    "price": 1299.99,
    "stock_status": "in_stock",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Collection (List):

{
  "data": [
    {
      "id": 123,
      "name": "Premium Laptop",
      "sku": "LAPTOP-001",
      ...
    },
    {
      "id": 124,
      "name": "Wireless Mouse",
      "sku": "MOUSE-001",
      ...
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 15,
    "to": 15,
    "total": 73
  },
  "links": {
    "first": "https://api.synthesq.com/api/v1/operations/products?page=1",
    "last": "https://api.synthesq.com/api/v1/operations/products?page=5",
    "prev": null,
    "next": "https://api.synthesq.com/api/v1/operations/products?page=2"
  }
}

Creation Success (201 Created):

{
  "message": "Product created successfully",
  "data": {
    "id": 125,
    "name": "Premium Laptop",
    ...
  }
}

Update Success (200 OK):

{
  "message": "Product updated successfully",
  "data": {
    "id": 123,
    "name": "Premium Laptop - Updated",
    ...
  }
}

Deletion Success (200 OK):

{
  "message": "Product deleted successfully"
}

HTTP Status Codes

The API uses standard HTTP status codes:

Success Codes

Code	Meaning	Description
200	OK	Request successful
201	Created	Resource created successfully
204	No Content	Request successful, no content to return

Client Error Codes

Code	Meaning	Description
400	Bad Request	Invalid request format
401	Unauthorized	Authentication required or failed
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
422	Unprocessable Entity	Validation failed
429	Too Many Requests	Rate limit exceeded

Server Error Codes

Code	Meaning	Description
500	Internal Server Error	Server-side error occurred
503	Service Unavailable	Service temporarily unavailable

Pagination

Collections are automatically paginated with 15 items per page by default.

Pagination Parameters:

# Get second page
GET /api/v1/operations/products?page=2

# Change page size (max 100)
GET /api/v1/operations/products?per_page=50

# Combined
GET /api/v1/operations/products?page=3&per_page=25

Pagination Metadata:

{
  "data": [...],
  "meta": {
    "current_page": 2,
    "from": 16,
    "last_page": 5,
    "per_page": 15,
    "to": 30,
    "total": 73
  },
  "links": {
    "first": "https://api.synthesq.com/api/v1/operations/products?page=1",
    "last": "https://api.synthesq.com/api/v1/operations/products?page=5",
    "prev": "https://api.synthesq.com/api/v1/operations/products?page=1",
    "next": "https://api.synthesq.com/api/v1/operations/products?page=3"
  }
}

Including Relationships

Use the include query parameter to load related data:

# Include product category and supplier
GET /api/v1/operations/products/123?include=category,supplier

# Include pricing details
GET /api/v1/operations/products/123?include=pricing

# Multiple includes
GET /api/v1/operations/products/123?include=pricing,inventory,category

Available Includes (vary by resource):

• pricing - Detailed pricing information (cost, margin)
• inventory - Full inventory details
• category - Product category
• supplier - Supplier information
• attributes - Product attributes (EAV)
• variants - Product variants
• media - Image gallery

See Sparse Fieldsets for more advanced response optimization.

Rate Limiting

API requests are rate-limited to ensure fair usage:

• Limit: 60 requests per minute per user
• Headers: Rate limit information is included in response headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642598400

When rate limit is exceeded, you'll receive a 429 Too Many Requests response:

{
  "message": "Too many requests. Please try again later.",
  "retry_after": 30
}

CORS

Cross-Origin Resource Sharing (CORS) is enabled for authorized domains. Contact your administrator to whitelist your domain.

Next Steps

• Learn about Sparse Fieldsets for performance optimization
• Understand Error Handling for robust integrations
• Explore the API Reference for endpoint details