[METHOD] /endpoint-path

Brief description of what this endpoint does (1-2 sentences).

When to Use This

Explain when and why someone would use this endpoint. Focus on practical use cases:

• Use Case 1: Specific scenario (e.g., "Sync leads to your dashboard")
• Use Case 2: Another scenario (e.g., "Generate custom reports")
• Use Case 3: Third scenario (e.g., "Integrate with external tools")

Authentication

Required: Yes/No

If authentication is required, specify which method:

• HTTP Basic Auth (client_id:client_secret)
• Bearer token (JWT)

Request

Endpoint: [METHOD] /endpoint-path

Headers:

Accept: application/json
Content-Type: application/json (for POST/PUT requests)

Example:

curl -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Accept: application/json" \
  "https://your-api.example.com/endpoint-path?param=value"

Path Parameters

Parameter	Required	Type	Description
id	Yes	string	Unique identifier for the resource

Query Parameters

Parameter	Required	Type	Description	Example
page	No	integer	Page number for pagination	1
limit	No	integer	Results per page (max 100)	25
filter	No	string	Filter criteria	active=true

Request Body (for POST/PUT)

Field	Required	Type	Description	Example
name	Yes	string	Resource name	"My Resource"
value	No	number	Numeric value	42
active	No	boolean	Active status	true

Example Request Body:

{
  "name": "My Resource",
  "value": 42,
  "active": true
}

Response

Success Response

Status: 200 OK (or 201 Created for POST, 202 Accepted for async)

Response Fields:

Field	Type	Description
id	string	Unique identifier
name	string	Resource name
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

Example Response:

{
  "id": "abc-123",
  "name": "My Resource",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

Paginated Response (if applicable)

When using page and limit parameters:

{
  "data": [
    {
      "id": "abc-123",
      "name": "Resource 1"
    },
    {
      "id": "def-456",
      "name": "Resource 2"
    }
  ],
  "total": 150,
  "page": 1,
  "limit": 25
}

Common Errors

Status Code	Error	Meaning	Solution
400	Bad Request	Invalid request parameters	Check parameter formats and required fields
401	Unauthorized	Missing or invalid credentials	Verify your client_id and client_secret
403	Forbidden	No permission to access this resource	Check OU permissions and user roles
404	Not Found	Resource doesn't exist	Verify the ID or path is correct
422	Unprocessable Entity	Validation failed	Review error message for specific field issues
429	Too Many Requests	Rate limit exceeded	Slow down requests or contact support for higher limits
500	Internal Server Error	Server-side error	Retry later or contact support if persistent

Example Error Response:

{
  "error": "validation_failed",
  "message": "Name is required",
  "details": {
    "field": "name",
    "code": "required"
  }
}

Important Notes

Organizational Unit (OU) Scoping

This endpoint is OU-scoped. Results are filtered by your active OU:

• Set active OU via /org-units/active before calling this endpoint
• Only returns data you have permission to access
• Multi-OU access requires proper role assignments

Pagination

When using page and limit:

• Default page: 1
• Default limit: 25
• Maximum limit: 100
• Response includes total, page, and limit metadata

Rate Limiting

• Standard rate limit: 100 requests per minute
• Burst allowance: 200 requests
• Rate limit headers included in response:
  • X-RateLimit-Limit: Maximum requests per minute
  • X-RateLimit-Remaining: Remaining requests
  • X-RateLimit-Reset: Unix timestamp when limit resets

Related Endpoints

• Related Endpoint 1 - Brief description
• Related Endpoint 2 - Brief description

Examples

Example 1: [Specific Use Case]

Describe what this example accomplishes.

curl -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Accept: application/json" \
  "https://your-api.example.com/endpoint-path?specific=params"

Response:

{
  "result": "example"
}

Example 2: [Another Use Case]

Describe another practical example.

curl -u "CLIENT_ID:CLIENT_SECRET" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}' \
  "https://your-api.example.com/endpoint-path"

Response:

{
  "result": "created"
}

Best Practices

1. [Specific Recommendation]: Explain why this matters
2. [Another Recommendation]: Practical advice
3. [Performance Tip]: How to optimize usage

See Also

• Main API Documentation
• Authentication Guide
• Related Feature Documentation