API reference
Technical reference for integrating with the Datar Platform API. Build custom integrations and extend the platform to fit your needs.
Overview
How the Datar API is structured
The Datar Platform exposes a type-safe API for all platform operations. All communication between the web app and mobile app uses this API. You can use it to build custom integrations, automate workflows, or connect Datar with other tools your organisation uses.
Every request passes through a consistent pipeline: the client sends a request, the API validates the input, checks authentication and permissions, executes the operation, and returns a structured response. The diagram below illustrates this flow.
Secure
Session-based authentication with HTTP-only cookies, fine-grained permissions, and comprehensive audit logging for all operations. Every request is verified before processing.
Consistent
All endpoints follow the same patterns for input validation, error handling, and response formatting. Predictable behaviour makes integration straightforward.
Extensible
The modular architecture makes it straightforward to add new endpoints and integrations. Each module operates independently while sharing common infrastructure for authentication, permissions, and notifications.
Data architecture
How data flows through the platform
Clients connect to the API layer via HTTPS. The API layer handles all business logic, validation, and access control before reading from or writing to the underlying storage. Data is cached at multiple levels: the API layer maintains short-lived in-memory caches for frequently accessed resources, and the client applications use query-level caching to reduce redundant network requests and improve responsiveness.
Web & Mobile
The web app and mobile app both consume the same API. A shared codebase ensures consistent behaviour across platforms. Client-side query caching reduces latency and keeps data fresh with automatic background re-fetching.
Type-safe API
Every request and response is fully typed. Input validation ensures that malformed data is rejected before it reaches the business logic layer, and errors are caught early rather than at runtime.
Secure storage
A managed database with cloud file storage. Encrypted at rest, fine-grained access controls, and full audit logging. All sensitive data is protected in transit and at rest using industry-standard encryption.
Authentication
How to authenticate with the API
The API uses session-based authentication. To make authenticated requests, you need a valid session token. Sessions are initiated when a user signs in via the web or mobile app, and the resulting token is stored as a secure, HTTP-only cookie that is automatically attached to every subsequent request.
Session tokens
After successful authentication, the server issues a session token stored as an HTTP-only cookie. This token is automatically included in subsequent requests. Tokens are cryptographically signed and cannot be tampered with. Each token is bound to the user's session and IP address for additional security.
Token lifecycle & refresh
Sessions are automatically refreshed while the user is active. Inactive sessions expire after a configurable period set by your administrator (typically 7–30 days). When a session expires, the API returns a 401 response and the client should redirect the user to the sign-in page. There is no need to manually refresh tokens — the platform handles this transparently.
Multi-device sessions
Users can have active sessions on multiple devices simultaneously. Each session is tracked independently. Administrators can revoke individual sessions or all sessions for a user from the admin panel.
Session expiry behaviour
When a session expires mid-request, the API returns a 401 Unauthorised response. Client applications should handle this by clearing any cached user state and prompting the user to sign in again. In-flight mutations are not committed if the session has expired.
Available endpoints
The API is organised by module
Each platform module exposes its own set of API procedures. The main endpoint groups are listed below with their key operations.
Requests
Create, read, update, and manage requests. Includes approval workflows, status transitions, and line item management.
Projects
Manage projects, tasks, timesheets, and sprints. Supports assignment, status tracking, and board views.
People
Employee profiles, timesheets, leave management, performance goals, and attendance.
Drive
File and folder management, uploads, sharing, permissions, and storage operations.
Inventory
Product and stock management, categories, locations, and stock level tracking.
Procurement
Tender management, purchase orders, vendor management, and budget tracking.
Additional shared endpoints are available for tags, permissions, comments, notifications, and search. These cross-cutting capabilities are accessible from within any module context.
Rate limits
Usage limits to keep the platform stable
To ensure reliable performance for all users, the API enforces rate limits on requests. If you exceed the limit, you will receive a 429 (Too Many Requests) response.
Standard requests
Up to 100 requests per minute per authenticated user. Sufficient for normal interactive use and moderate automation.
File uploads
File uploads have separate limits based on file size and your organisation's storage quota. Contact your administrator for details.
Batch operations
Batch endpoints have lower rate limits. Space out bulk operations to avoid hitting the limit.
Retry guidance
When you receive a 429 response, implement exponential backoff before retrying. Start with a 1-second delay, then double it on each subsequent retry (1s, 2s, 4s, 8s, etc.), up to a maximum of 60 seconds. Add a small amount of random jitter (e.g. 0–500ms) to prevent multiple clients from retrying in lockstep.
Rate limit headers are included in every API response to help you monitor your remaining quota:
X-RateLimit-LimitThe maximum number of requests allowed in the current window.
X-RateLimit-RemainingThe number of requests remaining before the limit is reached.
X-RateLimit-ResetThe Unix timestamp (in seconds) when the current rate limit window resets.
Error handling
How to handle API errors gracefully
The API uses standard HTTP status codes and returns structured error objects with details about what went wrong. Every error response includes a machine-readable code and a human-readable message to aid debugging.
The request was malformed or missing required fields. Check the error details for specific field-level validation messages. Common causes include missing required parameters, invalid data types, or values outside allowed ranges.
Your session has expired or you are not authenticated. Re-authenticate by redirecting the user to the sign-in page, then retry the request with the new session token. Do not retry automatically without re-authenticating.
You do not have permission to perform this action. Check that your role and item-level permissions are sufficient. This error is not resolved by re-authenticating — the user needs additional permissions granted by an administrator.
The requested resource does not exist or has been deleted. Verify the ID and check the trash if applicable. This may also occur if the user does not have visibility into the resource due to sharing settings.
The operation conflicts with the current state of the resource. This typically occurs when attempting to create a duplicate record, or when a concurrent update has modified the resource since you last fetched it. Re-fetch the resource and retry.
You have exceeded the rate limit. Wait before retrying. Implement exponential backoff in automated scripts. Check the X-RateLimit-Reset header to determine when you can resume making requests.
An unexpected error occurred on the server. This is not caused by your request and does not need to be corrected on your end. Retry after a brief delay. If the error persists, contact support and include the timestamp and any correlation ID returned in the response.
Best practices
Recommendations for reliable API integrations
Use pagination for list endpoints
Always use cursor-based pagination when fetching lists of records. Avoid fetching all records at once — this reduces response times, lowers memory usage, and prevents timeouts on large datasets. Request a reasonable page size (25–100 items) and iterate using the returned cursor.
Handle errors gracefully
Always check the HTTP status code and parse the error response body. Display user-friendly messages in the UI rather than raw error codes. Distinguish between retryable errors (429, 500) and non-retryable errors (400, 401, 403, 404) to avoid unnecessary retry loops.
Cache responses where appropriate
For data that changes infrequently (e.g. user profiles, organisation settings, catalogue items), cache the response on the client and use a stale-while-revalidate strategy. This reduces API calls, improves perceived performance, and makes your integration more resilient to transient network issues.
Design for idempotency
When performing write operations, design your integration so that retrying a failed request does not create duplicate records. Use unique client-generated identifiers where supported, and check for 409 Conflict responses to detect duplicate submissions.
Follow the principle of least privilege
Request only the permissions your integration needs. Avoid using administrator-level credentials for routine operations. Scope API access to the specific modules and actions required, and rotate credentials periodically.
Test in a non-production environment
Always develop and test your integration against a staging or development environment before deploying to production. This protects live data from accidental modifications and allows you to validate error handling paths without risk.
Frequently asked questions
Yes. Any application that can make HTTP requests can integrate with the Datar API. You will need valid authentication credentials and should follow the rate limit guidelines. For server-to-server use, store tokens securely and rotate them periodically.
Contact your administrator to request access to a development or staging environment for testing integrations without affecting production data. Sandbox data resets are common, so avoid relying on long-lived test records.
Report API issues to your organisation's IT administrator or contact the Datar support team directly. Include the endpoint, request payload, and error response to help with diagnosis. A timestamp and correlation ID (if returned) speeds triage.
The web and mobile apps use a shared TypeScript client. API documentation is available on request. For other languages, you can generate HTTP clients from the provided specification. Community libraries may also be available—check with your administrator or the Datar developer community.
Yes. Most modules support bulk operations via the API. For large datasets (1000+ records), use pagination and batch requests to avoid timeouts. Contact support for assistance with one-time migrations or data exports.
Did this page help you?
Your feedback helps us improve our documentation.