API Documentation

RosterOptic API Referencev1.0.1

Integrate your systems with RosterOptic's powerful REST API. Build custom workflows, sync staff data, and automate roster operations.

Need help? Contact support@rosteroptic.com support@rosteroptic.com

Request Access

Authentication

API Key Setup

Endpoints

Available Routes

Code Examples

JavaScript & cURL

Rate Limits

Quotas & Throttling

Error Handling

Response Format & Codes

Security

Best Practices

Autenticación

API Key Authentication

Authenticate requests using your API key in the Authorization header. Authorization:

Authorization: Bearer YOUR_API_KEY

All API keys are passed via the Authorization header. x-api-key.API keys start with 'ro_' followed by a unique identifier. Bearer.Keys are stored securely and can be rotated at any time.

Getting Your API Key

1Navigate to Settings → API Keys in your dashboard
2Click 'Create API Key'
3Give your key a descriptive name (e.g., 'Production Integration')
4Select the appropriate scopes for your use case
5Copy the key immediately (it won't be shown again)

You can manage and revoke keys at any time from the Settings page.

Scopes

API keys can be scoped to limit access:

read:staff, write:rosters, read:reports

URL Base

All API endpoints are relative to:

https://api.rosteroptic.com/v1

Replace with your regional endpoint if applicable.

Endpoints

Staff

GET/api/staffSessionList all staff members

POST/api/staffSession or API KeyCreate a new staff member

GET/api/staff/[id]SessionGet staff details

PUT/api/staff/[id]Session or API KeyUpdate staff information

DELETE/api/staff/[id]Session or API KeyDelete a staff member

Roster

GET/api/rosterSessionFetch roster for date range

POST/api/roster/generateSession or API KeyTrigger AI roster generation

POST/api/roster/commitSession or API KeyCommit draft roster

PATCH/api/roster/[id]Session or API KeyUpdate a shift assignment

DELETE/api/roster/[id]Session or API KeyDelete a shift

GET/api/roster/coverageSession or API KeyGet coverage analytics

GET/api/roster/metricsSession or API KeyGet roster metrics

Other Resources

GET/api/sitesSession or API KeyList work sites

POST/api/sitesSession or API KeyCreate a new site

GET/api/complianceSession or API KeyGenerate compliance report

GET/api/swapsSessionList shift swap requests

PATCH/api/swaps/[id]Session or API KeyUpdate swap request status

GET/api/shift-patternsSessionList shift patterns

GET/api/annual-leaveSessionList leave requests

GET/api/reportsSession or API KeyGenerate custom reports

Manejo de Errores

All errors return JSON with the following format:

{
  "success": false,
  "error": "Error description"
}

field - The field that caused the error details details - Additional error information

200200 - Success

400400 - Bad Request

401401 - Unauthorized

403403 - Forbidden

404404 - Not Found

409409 - Conflict

422422 - Validation Error

429429 - Too Many Requests

500500 - Internal Server Error

Límites de Tasa

Default rate limit:: 1000 requests per hour
Configurable up to:: 10000 requests per hour (Enterprise plans)
If exceeded:: HTTP 429 response with Retry-After header

Note: Rate limit headers are included in all responses.

Ejemplos de Código

JavaScript

Recommended

fetch('https://api.rosteroptic.com/v1/staff', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
}).then(res => res.json()).then(data => console.log(data));

Always store your API key securely. Never expose it in client-side code.

cURL

curl -X GET 'https://api.rosteroptic.com/v1/staff' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json'

Seguridad

Security Requirements

Never share your API key in public repositories
Never embed API keys in client-side code
Never log API keys in plaintext
Never use API keys for user-facing authentication
Never store API keys in version control

Best Practices

Use environment variables to store keys
Rotate keys regularly (every 90 days)
Use scoped keys with minimal permissions
Monitor API usage for anomalies
Set up IP whitelisting when possible

Ready to integrate?

Get your API key from the Settings page and start building.

Go to Dashboard Contact Support

API Documentation

RosterOptic API Referencev1.0.1

Integrate your systems with RosterOptic's powerful REST API. Build custom workflows, sync staff data, and automate roster operations.

Need help? Contact support@rosteroptic.com support@rosteroptic.com

Request Access

Authentication

API Key Setup

Endpoints

Available Routes

Code Examples

JavaScript & cURL

Rate Limits

Quotas & Throttling

Error Handling

Response Format & Codes

Security

Best Practices

Autenticación

API Key Authentication

Authenticate requests using your API key in the Authorization header. Authorization:

Authorization: Bearer YOUR_API_KEY

All API keys are passed via the Authorization header. x-api-key.API keys start with 'ro_' followed by a unique identifier. Bearer.Keys are stored securely and can be rotated at any time.

Getting Your API Key

1Navigate to Settings → API Keys in your dashboard
2Click 'Create API Key'
3Give your key a descriptive name (e.g., 'Production Integration')
4Select the appropriate scopes for your use case
5Copy the key immediately (it won't be shown again)

You can manage and revoke keys at any time from the Settings page.

Scopes

API keys can be scoped to limit access:

read:staff, write:rosters, read:reports

URL Base

All API endpoints are relative to:

https://api.rosteroptic.com/v1

Replace with your regional endpoint if applicable.

Endpoints

Staff

GET/api/staffSessionList all staff members

POST/api/staffSession or API KeyCreate a new staff member

GET/api/staff/[id]SessionGet staff details

PUT/api/staff/[id]Session or API KeyUpdate staff information

DELETE/api/staff/[id]Session or API KeyDelete a staff member

Roster

GET/api/rosterSessionFetch roster for date range

POST/api/roster/generateSession or API KeyTrigger AI roster generation

POST/api/roster/commitSession or API KeyCommit draft roster

PATCH/api/roster/[id]Session or API KeyUpdate a shift assignment

DELETE/api/roster/[id]Session or API KeyDelete a shift

GET/api/roster/coverageSession or API KeyGet coverage analytics

GET/api/roster/metricsSession or API KeyGet roster metrics

Other Resources

GET/api/sitesSession or API KeyList work sites

POST/api/sitesSession or API KeyCreate a new site

GET/api/complianceSession or API KeyGenerate compliance report

GET/api/swapsSessionList shift swap requests

PATCH/api/swaps/[id]Session or API KeyUpdate swap request status

GET/api/shift-patternsSessionList shift patterns

GET/api/annual-leaveSessionList leave requests

GET/api/reportsSession or API KeyGenerate custom reports

Manejo de Errores

All errors return JSON with the following format:

{
  "success": false,
  "error": "Error description"
}

field - The field that caused the error details details - Additional error information

200200 - Success

400400 - Bad Request

401401 - Unauthorized

403403 - Forbidden

404404 - Not Found

409409 - Conflict

422422 - Validation Error

429429 - Too Many Requests

500500 - Internal Server Error

Límites de Tasa

Default rate limit:: 1000 requests per hour
Configurable up to:: 10000 requests per hour (Enterprise plans)
If exceeded:: HTTP 429 response with Retry-After header

Note: Rate limit headers are included in all responses.

Ejemplos de Código

JavaScript

Recommended

fetch('https://api.rosteroptic.com/v1/staff', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
}).then(res => res.json()).then(data => console.log(data));

Always store your API key securely. Never expose it in client-side code.

cURL

curl -X GET 'https://api.rosteroptic.com/v1/staff' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json'

Seguridad

Security Requirements

Never share your API key in public repositories
Never embed API keys in client-side code
Never log API keys in plaintext
Never use API keys for user-facing authentication
Never store API keys in version control

Best Practices

Use environment variables to store keys
Rotate keys regularly (every 90 days)
Use scoped keys with minimal permissions
Monitor API usage for anomalies
Set up IP whitelisting when possible

Ready to integrate?

Get your API key from the Settings page and start building.

Go to Dashboard Contact Support