Skip to main content

API Overview

The Fuuffy API is organized around REST principles. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL​

All API requests should be made to:

EnvironmentBase URL
Testinghttps://testing-api-gateway.fuuffy.com/v1
Productionhttps://api-gateway.fuuffy.com/v1

API Versioning​

The current API version is v1. The version is included in the URL path.

Request Format​

Headers​

All requests should include the following headers:

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

Request Body​

Request bodies should be JSON-encoded:

{
  "field": "value",
  "nested": {
    "field": "value"
  }
}

Response Format​

All successful responses are wrapped in a data object following Fuuffy's standard response format.

{
  "data":{
    "id": "order_12345678",
    "status": "pending",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Success Responses​

Status CodeDescription
200 OKRequest succeeded

Error Responses​

Error responses include an error code and message:

{
  "error": {
    "code": "invalid_request",
    "message": "The 'recipient' field is required",
    "field": "recipient"
  }
}
Status CodeDescription
400 Bad RequestInvalid request parameters
401 UnauthorizedInvalid or expired access token
403 ForbiddenInsufficient permissions
404 Not FoundResource not found
429 Too Many RequestsRate limit exceeded
500 Internal Server ErrorServer error

Rate Limiting​

API requests are rate-limited to ensure fair usage:

• Standard: 100 requests per minute
• Burst: 1000 requests per hour

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642248600

When you exceed the rate limit, you'll receive a 429 response:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please try again later.",
    "retry_after": 60
  }
}

Pagination​

List endpoints support pagination using cursor-based pagination:

Request Parameters​

limit
integer
Number of items to return.
Example: 20 or ?limit=20
offset
integer
Number of items to skip.
Example: 0 or ?offset=20

Example Request​

curl "${API_URL}/v1/orders?limit=20&offset=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response​

{
  "data": [
    { "id": "order_1", "status": "delivered" },
    { "id": "order_2", "status": "in_transit" }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}

Idempotency​

To safely retry requests without performing the same operation twice, include an Idempotency-Key header:

POST /v1/orders
Idempotency-Key: unique-key-123

Key requirement The key should be a unique string (e.g. UUID). Requests with the same key will be idempotent and may return 500 if the key already exists within 30 days.

Response​

{
    "error": {
        "code": 500998,
        "code_reason": "idempotency_key_exists",
        "message": "Same idempotency_key exists, please do not submit again within 30 days"
    }
}

Webhooks​

Coming Soon

Testing​

Sandbox Environment​

Use our sandbox environment for testing:

Base URL
https://testing-api-gateway.fuuffy.com/v1/
Credentials
Separate from production. Get your API key from support@fuuffy.com.

Support​

• Documentation: docs.fuuffy.com
• Email: support@fuuffy.com