API Introduction

Welcome to the Curosa API v1

The Curosa API allows you to programmatically manage your supplier account, products, orders, and inventory. Our REST API uses standard HTTP methods and returns JSON responses.

Base URL

All API requests should be made to:

https://api.curosa.com/v1

Authentication

The Curosa API uses API keys for authentication. You can generate API keys from your supplier dashboard under Settings → API Keys.

Include your API key in the Authorization header:

curl -X GET "https://api.curosa.com/v1/products" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Format

All responses are returned in JSON format:

{
  "data": {
    "id": "prod_123",
    "name": "Example Product",
    "sku": "EX-001"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Error Handling

When an error occurs, the API returns an appropriate HTTP status code and error details:

Error response format:

{
  "error": {
    "code": "invalid_parameter",
    "message": "The 'sku' field is required",
    "field": "sku"
  }
}

Pagination

List endpoints use cursor-based pagination for efficient navigation through large datasets. Cursor-based pagination provides better performance and consistency when data is being updated frequently.

Requesting Pages

To fetch the next page of results, use the cursor query parameter with the value from the meta.next_cursor field in the previous response:

curl -X GET "https://api.curosa.com/v1/products?cursor=eyJwcm9kdWN0cy5pZCI6MTAwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9" \
  -H "Authorization: Bearer YOUR_API_KEY"

Paginated Response Format

Paginated responses include navigation links and metadata:

{
  "data": [
    {
      "sku": "T3272P287613",
      "platform_sku": "367.983.903",
      "name": "Example Product"
    }
  ],
  "links": {
    "first": null,
    "last": null,
    "prev": null,
    "next": "https://api.curosa.com/v1/products?cursor=eyJwcm9kdWN0cy5pZCI6MTAwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"
  },
  "meta": {
    "path": "https://api.curosa.com/v1/products",
    "per_page": 100,
    "next_cursor": "eyJwcm9kdWN0cy5pZCI6MTAwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
    "prev_cursor": null
  }
}

Response Fields:

• links: Navigation links for pagination
  • first: Link to the first page (usually null for cursor-based pagination)
  • last: Link to the last page (usually null for cursor-based pagination)
  • prev: Link to the previous page (use meta.prev_cursor if available)
  • next: Link to the next page (use meta.next_cursor if available)
• meta: Pagination metadata
  • path: The base path for this endpoint
  • per_page: Number of items per page (varies by endpoint)
  • next_cursor: Cursor token for the next page (use in cursor query parameter)
  • prev_cursor: Cursor token for the previous page (use in cursor query parameter, or null if on the first page)

Navigating Pages

• First page: Make a request without the cursor parameter
• Next page: Use meta.next_cursor value in the cursor query parameter
• Previous page: Use meta.prev_cursor value in the cursor query parameter (if available)
• No more pages: When meta.next_cursor is null, you've reached the end of the results

Next Steps

• Authentication - Learn about API key management and scopes
• Rate Limiting - Understand rate limits and best practices
• Products - Manage your product catalog