# Resources in the REST API This describe the resources that make up the official TextMaster REST API. If you have any problems or requests, please contact [TextMaster support](mailto:support@textmaster.com). ### Version The current version of our API is **v1**. You must explicitly request this version by appending the version number at the end of the URL. ``` https://api.textmaster.com/v1/ ``` ### Schema All API access is done over HTTPS, and accessed from `https://api.textmaster.com/`. All data is sent and received as JSON. ```shell $ curl -i https://api.textmaster.com/ping > HTTP/1.1 200 OK > X-Frame-Options: SAMEORIGIN > X-XSS-Protection: 1; mode=block > X-Content-Type-Options: nosniff > Content-Type: application/json; charset=utf-8 > Cache-Control: no-store, must-revalidate, private, max-age=0 > X-Request-Id: f73733ca-a8be-47ba-981d-fc22ef01865f > X-Runtime: 0.238097 > Vary: Origin > X-MiniProfiler-Original-Cache-Control: max-age=0, private, must-revalidate > X-MiniProfiler-Ids: uhw0tm64jxvyu121sxkc > Set-Cookie: __profilin=p%3Dt; path=/; HttpOnly > Transfer-Encoding: chunked {"message":"Textmaster API at your service"} ``` All timestamps return an [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format: ``` YYYY-MM-DDTHH:MM:SSZ ``` ### Environment A sandbox environment is made available for tests and can be accessed from `https://api.textmasterstaging.com/`. It behaves the same way as the production environment. ### Parameters Many API endpoints take optional parameters. For `GET` requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter. ```shell curl "https://api.textmaster.com/v1/public/expertises/5f7dcc7d8b819239aff5af7c/sub_expertises?locale=en-EU" ``` In this example, the `5f7dcc7d8b819239aff5af7c` value is provided for the `:expertise_id` parameter in the path while `:locale` is passed in the query string. For `POST`, `PATCH`, `PUT` and `DELETE` requests, parameters not included in the URL should be encoded as JSON with a `Content-Type` header set to `application/json`. ```shell curl -X PUT \ -H "Content-Type: application/json" \ -d '{"my_author":{"description":"new description"}}' \ https://api.textmaster.com/v1/clients/my_authors/5f7dcc3c8b819239aff5a391 ``` ### Client Errors There are four possible types of client errors on API calls that receive request bodies: #### Bad Request Sending invalid JSON will result in a `400 Bad Request` response. ``` HTTP/1.1 400 Bad Request {"errors":{"base":["Invalid Request."]}} ``` #### Method Not Allowed Sending an unsupported HTTP verb will result in a `405 Method Not Allowed` response. ``` HTTP/1.1 405 Method Not Allowed {"errors":{"base":["Method Not Allowed."]}} ``` #### Not Acceptable Sending or requesting an unsupported format will result in a `406 Not Acceptable` response. ``` HTTP/1.1 406 Not Acceptable {"errors":{"base":["Unacceptable Request."]}} ``` #### Unprocessable Entity Sending invalid data will result in a `422 Unprocessable Entity` response. ``` HTTP/1.1 422 Unprocessable Entity {"errors":{"base":["Error: Object could not be changed."]}} ``` ### HTTP redirects The API uses HTTP redirection where appropriate. Clients should assume that any request may result in a redirection. Receiving an HTTP redirection is *not* an error and clients should follow the redirect. Redirect responses will have a `Location` header field which contains the URI of the resource to which the client should repeat the requests. | Status Code | Description | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 301 | Permanent redirection. The URI you used to make the request has been superseded by the one specified in the `Location` header field. This an all future requests to this resource should be directed to the new URI. | | 302, 307 | Temporary redirection. The request should be repeated verbatim to the URI specified in the `Location` header field but clients should continue to use the original URI for future requests. | Other HTTP status codes may be used in accordance to the [HTTP 1.1 specification](https://datatracker.ietf.org/doc/html/rfc2616). ### HTTP verbs Where possible, the API strives to use appropriate HTTP verbs for each action. | Verb | Description | | ------ | -------------------------------------------- | | GET | Used for retrieving resources. | | POST | Used for creating resources. | | PUT | Used for replacing resources or collections. | | DELETE | Used for deleting resources. | ### Pagination Requests that return multiple items will be paginated to 100 items by default. You can specify further pages with the `page` parameter. For some resources, you can also set a custom page size up to 100 with the `per_page` parameter. Note that for technical reasons, not all endpoints will honour this parameter. ```shell curl 'https://api.textmaster.com/v1/clients/projects?page=2&per_page=100' ``` Note that page numbering is 1-based and that omitting the `page` parameter will return the first page. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developer.textmaster.com/overview/resources-in-the-rest-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.