API Reference

The Hopshift API gives partner systems and integrations programmatic access to data in your Hopshift group. Use it to sync employee records into external HR tools, reporting systems, payroll integrations, or any other service that needs reliable access to your workforce data.

Base URL

All API endpoints are served from:

https://hopshift.nottoosweetlabs.com

Versioned endpoints live under the /api/v1/ prefix. Always use the versioned path: unversioned paths are internal and may change without notice.

https://hopshift.nottoosweetlabs.com/api/v1/employees

Authentication

The Hopshift API uses API keys for authentication. Keys are created in your Hopshift dashboard under Group Settings → API Keys and must be sent as a Bearer token on every request.

curl https://hopshift.nottoosweetlabs.com/api/v1/employees \
  -H "Authorization: Bearer hops_your_api_key_here"

Keys are group-scoped: a single key covers all companies within your group. See Authentication for full details on creating keys, scopes, and security practices.

Versioning

The API is versioned with a /v1/ path prefix. Breaking changes will be introduced under a new version prefix (/v2/) and the old version will remain available with advance notice of deprecation.

Non-breaking additions (new optional fields, new endpoints) may be added to the current version at any time.

Rate Limiting

All API keys are subject to a rate limit of 200 requests per minute. When this limit is exceeded the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying. See Rate Limiting for implementation guidance.

Available Endpoints

Response Format

All responses are JSON. Successful responses follow this envelope:

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150,
    "total_pages": 3
  }
}

Error responses always include an "error" string field:

{
  "error": "Unauthorized"
}

HTTP Status Codes