Overview

Welcome to our API. These pages document all the available HTTP requests and their data format and schemes.

All requests to the API go through this URL:

Main API URL

https://api.theca.com/v1/

We also have a test environment. Access to it is granted separately with another API token.

Test API URL

https://api.test.theca.com/v1/

Theca API tokens

The first step in using our API is to acquire a Theca-Client-Token. The client token is a long string that uniquely identifies each client and must be added to each API request. Though some requests are open for all users. API requests to closed requests without a Theca-Client-Token will be rejected with a 401 Unauthorized HTTP status. Note that tokens may be revoked by Theca, e.g., if they are compromised or if a token generating service is implemented in a future version of the API.

A Theca-User-Token is also required to identify which user is making requests. Requests using the same user token will be grouped together to filter bot traffic from statistics and to improve the search results. The provided token will be one-way encrypted (i.e., hashed). Though, it is still not recommended to use sensitive user data for this parameter, such as e-mails or usernames. Internal user IDs or session tokens are both recommended. The maximum size is 255 bytes, the remainder will be discarded.

caution

Do not prefix the headers with X- (this is a deprecated custom for custom HTTP header parameters).

Parameter	Type	Description
Theca-Client-Token	Text	Provided by Theca to identify the client making the request.
Theca-User-Token	Text	Chosen to persistently identifying users across queries.

Query parameters

Parameters to requests are sent as query parameters. These are described for each request in the following pages. Some parameters are optional, which is denoted with a question mark in the type column. See the following example.

Parameter	Type	Description
example	Text	This parameter is a mandatory string.
optional	Integer?	This parameter is an optional integer.

Formats

Search result data can be returned in either application/json or application/ld+json format. The client chooses which format to use with the HTTP Accept header parameter. The data types of result objects are documented in the same way as the query parameters above.

JSON

The data will be returned in RFC8259 JSON standard. The charset is always UTF-8 and no characters except " and \ will be escaped. JSON is the default if no Accept parameter is provided or if / is used. When there are multiple possible return values, the @type-field is used to disambiguate which type is the currently returned one.

LD-JSON

Returned data follows the LD-JSON RDF format from https://schema.org/. The data will have no Theca extensions, so

ItemList will be used instead of [ResultList](search/result#thecaresultlist). The structure is equivalent to application/json but the `@type` of all objects are always included which might make development easier. The data returned can be validated at https://validator.schema.org/.

Note that properties with the enum type will have values prefixed with https://schema.org/ as per the specification. For example, when using LD-JSON the item availability property of in stock will be just "availability": "InStock" for application/json but will be "availability": https://schema.org/InStock for LD-JSON.

tip

You can place LD-JSON content in a script tag on HTML pages to have content from Theca's API be searchable from other search engines. A good way of complementing inspirational content with a dynamic yet SEO friendly product listing.

Versions

The latest major version of the API is v1.

If major updates are conducted to the API a new version will be made available under e.g. v2 instead of v1. A major update is defined as:

• Changing the overall request of any endpoint, e.g. URL path, HTTP method, or Content-Types.
• Adding new mandatory query parameters or header parameters.
• Adding or removing mandatory attributes in the responses
• Changing the data types of any attribute in the responses

Minor updates to the API will not result in a new version. This includes for example:

• Adding new optional query or header parameters.
• Adding new attributes to the response of an API request.
• Removing attributes marked as optional to the response of an API request.
• Changing the HTTP status code for an error.
• Fixing errors in the normalization or deduplication behavior of the crawler of the data in an index. These are all classified as minor updates and should be considered as backwards compatible. Hence, they should not affect your integration with the API.

note

Optional parameters or attributes are affixed with a question mark (?) to their types in the documentation.