API Standards & Conventions

This guide outlines the key technical conventions and policies that apply when working with SysAid's public API. It includes data formats, pagination, rate limiting, entity update safeguards, and more.

📄Supported Data Formats

SysAid’s API expects requests and responses to use standardized formats:

• Content Type: application/json
• Date/Tme Format: ISO 8601 (UTC)
  Example: 2024-06-10T14:32:00Z
  This format represents the date and time in Coordinated Universal Time (UTC), using the ISO 8601 standard.

📚Pagination

SysAid APIs implement offset-based pagination using two key parameters:

• limit (optional):
  The number of items returned per page.
  Default: 20 | Max: 500
• offset (optional):
  Used to calculate the starting point for the page of results.
  Formula: (page - 1) * limit (Note: page index starts at 1)

Example:

GET /api/v1/incidents?limit=50&offset=100

🚦Rate Limiting Policy

SysAid enforces rate limits on its REST API to ensure stability, performance, and scalability.

• Limit: Up to 1,000 requests per 5-minute window
• Scope: Rate limits are enforced at the account level
• Exceeded Limit Response:
  • HTTP Status Code: 429 Too Many Requests
  • Retry permitted after the cooldown period ends

⏳Monitoring Cooling Time

To help developers monitor their current rate limit usage and remaining cooldown time, the API includes the following HTTP response headers:

• X-RateLimit-Limit
  Indicates the total number of requests allowed per time window (daily or per 5 minutes)
• X-RateLimit-Remaining
  Shows how many requests you have left in the current time window
• X-RateLimit-Reset
  Displays the number of UTC epoch seconds remaining until the current rate limit window resets

These headers allow for smarter retry logic and can be parsed programmatically to manage API request pacing.

🔐Entity Update Locking (Optimistic Concurrency Control)

SysAid uses a version-based locking mechanism for mutable entities to maintain data integrity during updates.

How it works:

• Each entity contains a version parameter.
• When updating, you must supply the current version of the entity.
• If the version in your request does not match the version stored in the system, the update is rejected.

This ensures that updates are made only to the most recent entity state, preventing accidental overwrites.

👥Account User Quotas

SysAid enforces account-level quotas based on your license. These quotas limit the total number of agents and end users that can be created within an account.

SysAid’s API will validate and enforce these limits consistently across these user-related endpoints:

1. Create New End User / Create New Agent APIs
2. Convert to Agent API

Error Response Format

When a quota is exceeded, the following error will be returned:

{
  "statusCode": 403,
  "message": "Agent quota exceeded" // or "End user quota exceeded"
}

To increase your quota, please reach out to your Account Manager or our Support team.