Overview

Environments

The API is available in two environments:

Environment	Base URL	Description
API Staging	https://api.hub.staging.webmix.app	Development and testing environment
API Production	https://api.hub.webmix.app	Production environment

Authentication

The API uses a two-level authentication system: tenant authentication and user authentication.

Tenant Authentication

Tenant authentication is required for all API requests. The x-tenant-token header identifies which tenant is making the request.

Header: x-tenant-token

Required: Yes, for all endpoints

Purpose: Identifies the tenant making the request. This is mandatory for all API calls to ensure proper data isolation and tenant-specific configuration.

Example:

x-tenant-token: tenant-token-here

User Authentication

User authentication is required only for private (non-public) routes. The x-token header contains the user's authentication token.

Header: x-token

Required: Only for private/protected routes

Purpose: Authenticates the user making the request. This token is obtained through authentication endpoints (e.g., sign-in, sign-up).

When to include:

• Required for all private/protected endpoints
• Optional for public endpoints (e.g., public sign-up, public sign-in)

Example:

x-token: user-auth-token-here

Authentication Summary

Header	Required For	Purpose
x-tenant-token	All endpoints	Tenant identification
x-token	Private routes only	User authentication

Required Headers

The following headers are mandatory for all API requests:

Header	Description	Example
x-locale	Language locale code	tr
x-country	Country code (ISO 3166-1 alpha-2)	TR
x-device-id	Unique device identifier	123456
x-client-version	Client application version	1.0.0
x-platform	Platform name	ios, android, web
x-platform-version	Platform version	18.0.0

Content Type

All API requests should include the Content-Type header:

Content-Type: application/json

All responses are returned as JSON with the Content-Type: application/json header.

Response Format

All API responses follow a consistent structure with metadata and either data or error information.

Success Response

A successful response contains a meta object and a data object:

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "data": {
    "id": "1234",
    "title": "Test"
  }
}

For endpoints that return collections, the data field will be an array:

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "data": [
    {
      "id": "1234",
      "title": "Test"
    },
    {
      "id": "5678",
      "title": "Another Item"
    }
  ]
}

Error Response

An error response contains a meta object and an error object.

Validation Error Example:

When validation errors occur, the response includes a validation field.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "The request could not be processed.",
    "code": "VALIDATION_ERROR",
    "status": 400,
    "validation": {
      "email": "Invalid email address",
      "password": "Must be at least 8 characters"
    }
  }
}

Error with Detail Example:

For other error types, the response may include a detail field. The structure of detail varies based on the error code.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "Resource not found",
    "code": "RESOURCE_NOT_FOUND",
    "status": 404,
    "detail": {
      "resourceId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "resourceType": "user"
    }
  }
}

Error Object Fields:

• message (required): Human-readable error message
• code (required): Machine-readable error identifier
• status (required): HTTP status code
• validation (optional): Object containing validation errors
• detail (optional): Additional error information. Type: unknown. Structure varies based on the error code.

HTTP Status Codes

The API uses standard HTTP status codes to indicate the result of a request:

Status Code	Name	Description
200	OK	Request succeeded. The response body contains the requested data.
201	Created	Resource successfully created. The response body contains the created resource.
204	No Content	Request succeeded, but there is no content to return.
400	Bad Request	The request is malformed or contains invalid parameters.
401	Unauthorized	Authentication required or authentication failed.
403	Forbidden	The request is valid, but the user doesn't have permission to access the resource.
404	Not Found	The requested resource does not exist.
409	Conflict	The request conflicts with the current state of the resource.
422	Unprocessable Entity	The request is well-formed but contains semantic errors.
429	Too Many Requests	Rate limit exceeded. Too many requests in a given time period.
500	Internal Server Error	An unexpected error occurred on the server.
502	Bad Gateway	The server received an invalid response from an upstream server.
503	Service Unavailable	The service is temporarily unavailable.

Error Codes

Error responses include a code field that provides a machine-readable error identifier. For detailed information about all error codes, see the Error Codes documentation.

Date and Time Format

All timestamps in API responses are returned in ISO 8601 format with UTC timezone:

2025-01-15T10:30:00.000Z

ID Format

All resource IDs use the ULID (Universally Unique Lexicographically Sortable Identifier) format. ULIDs are 26 characters long and are URL-safe.

Example:

01ARZ3NDEKTSV4RRFFQ69G5FAV

Field Naming Conventions

All API request and response fields use camelCase naming convention.

Examples:

• userId
• createdAt
• phoneNumber

Timeouts

API requests have a default timeout of 5 seconds. Some endpoints may have shorter or longer timeout values depending on their operation complexity. Check individual endpoint documentation for specific timeout values.

When a request times out, the API will return a timeout error. Implement appropriate retry logic and error handling for timeout scenarios.

Rate Limiting

API requests are subject to rate limiting to ensure fair usage and system stability. Rate limits are applied per tenant and may vary based on the endpoint and subscription tier.

When rate limits are exceeded, the API will return a 429 Too Many Requests status code with details about the rate limit in the error response.

Rate Limit Headers

Rate limit information is included in response headers:

• X-RateLimit-Limit: Maximum number of requests allowed
• X-RateLimit-Remaining: Number of requests remaining in the current window
• X-RateLimit-Reset: Timestamp when the rate limit window resets

Request ID

Every API response includes a requestId in the meta object. This unique identifier can be used for debugging and support purposes. Please include the requestId when reporting issues or contacting support.

Support

For issues, questions, or API-related assistance, include the following information when reporting:

• Request ID: The requestId from the API response (found in the meta object)
• Endpoint: The API endpoint you were calling
• Request Body: The request payload (if applicable)
• Error Response: The complete error response you received
• Timestamp: When the issue occurred
• Platform: Your platform (ios, android, web)
• Client Version: Your application version

Resources

• Documentation: Detailed information about endpoints and error codes
• Error Codes: See the Error Codes page for detailed error information
• Contact: murat.camci@webmix.app

Changelog

This section tracks significant changes to the API, including new features, improvements, and breaking changes.

Versioning

API changes are documented with version numbers and release dates. Breaking changes are clearly marked and may require updates to integrations.

Recent Changes

For the complete changelog and detailed information about all API changes, see the Changelog page.