> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.kota.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kota.io/_mcp/server. # API Introduction > Introduction to the Kota API ## Introduction We've designed Kota Embedded around payroll, employer of record and HR platforms with specific use-cases available to different platforms so you don't have to worry about compliance and can focus on offering a great customer experience. ### Scoping out an integration? Check out our documentation to [plan your integration](/get-started/api-basics). ##### Base URL #### Production ```text https://api.kota.io ``` #### Test ```text https://test.api.kota.io ``` --- ## Authentication The Kota API uses API keys to authenticate requests. Test mode secret keys have the prefix `pk_test_` and live mode secret keys have the prefix `pk_live_`. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. Authentication to the API is performed via Bearer Auth. Provide your API key as the bearer token value in the Authorization header. Use `-H "Authorization: Bearer YOUR_API_SECRET_KEY"` in your request. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. API keys are tied to an individual platform and are restricted to that platform's type, such as `employer_of_record` and `payroll_provider`. Some endpoints are restricted to specific types and they are clearly noted in this API reference. **`AUTHENTICATED REQUEST`** ```curl AUTHENTICATED REQUEST curl https://api.kota.io/ENDPOINT \ -H "Authorization: Bearer YOUR_API_SECRET_KEY" \ ``` --- ## Errors Kota uses conventional HTTP response codes to indicate the success or failure of an API request. In general: * Codes in the `2xx` range indicate success. * Codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted). You should not retry the same request, except for the `429` status code. * Codes in the `5xx` range indicate an error with Kota's servers (these are rare). You can retry the same request. [Learn more about specific errors here](/api-reference/errors). ### The Error object In the event of an error, Kota will return an error object conform to the [Problem Details for HTTP APIs specification](https://www.rfc-editor.org/rfc/rfc9457.html). The error object has at the following properties. Additional properties may be included for specific errors, see the [detailed error documentation](/api-reference/errors). #### Properties typestring A URI reference that identifies the problem type. title string A short, human-readable summary of the problem type. status integer The HTTP status code generated by the server for this occurrence of the problem. error_code string A specific error code representing the error condition. trace_id stringOptional A unique identifier for this particular occurrence of the problem, for troubleshooting purposes. detail stringOptional A human-readable explanation specific to this occurrence of the problem. errors objectOptional An object containing error messages related to specific request properties.
HTTP STATUS CODE SUMMARY
200 OK Everything worked as expected.
400 Bad Request The request was unacceptable, often due to missing a required parameter.
401 Unauthorized No valid API key provided.
403 Forbidden The API key doesn’t have permissions to perform the request.
404 Not Found The requested resource doesn’t exist.
429 Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500 Server Error Something went wrong on Kota's end. (These are rare.)
--- ## Idempotent requests The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. When creating or updating an object, use an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of creating a second object or performing the update twice. To perform an idempotent request, provide an additional header to the request: `"Idempotency-Key: YOUR_IDEMPOTENT_KEY"` The idempotency key is a unique identifier that Kota's servers use to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with at least 30 characters of entropy to avoid collisions. Idempotency keys are linked with your authentication token and are up to 200 characters long with an expiration of 1 hour. The idempotency layer compares incoming parameters to those of the original request. If the parameters match we'll return exactly the same response as before without re-executing the request. If they do not match it will return a [409 Conflict](/api-reference/errors#idempotency-error) error to prevent accidental misuse. We save results only after the execution of an endpoint completes successfully. If incoming parameters fail validation, or the request conflicts with another request that’s executing concurrently we will discard the data of the subsequent request. You can retry these requests. All POST requests accept idempotency keys. Don’t send idempotency keys in GET, PUT and DELETE requests because it has no effect. These requests are idempotent by definition. **`IDEMPOTENT REQUEST`** ```curl IDEMPOTENT REQUEST curl https://api.kota.io/ENDPOINT \ -H "Authorization: Bearer YOUR_API_SECRET_KEY" \ -H "Idempotency-Key: KG5LxwFBepaKHyUD" \ ```