GoSearch API Documentation (1.1.0)
Welcome to the GoSearch API! You can use this API to access our endpoints, such as the Data Source API, to add a data connector we do not have support for! To access our API, you need to be on the GoSearch Enterprise plan. You can upgrade to the Enterprise plan by reaching out to the sales team.
The GoSearch API uses access tokens to authenticate requests. The access token must be included in the Authorization header of your request. To generate an access token, use the "Developer Tools" tab on GoSearch. Please note that only companies on the Enterprise plan are eligible for API tokens.
Once you have an access token, you can use it to make requests to the API. Requests are authenticated using HTTP Bearer Authentication. You must provide the access token in the Authorization header:
Authorization: Bearer {ACCESS_TOKEN}
If you do not provide an access token, or the token is not recognized, you will receive an error message with a 401 status code.
{
"error": {
"message": "The API token is not valid or is deactivated.",
"code": 401,
"type": "not_authorized"
}
}
If the token is recognized but has been disabled, the 401 response says so explicitly. Generate a new token from the "Developer Tools" tab and replace it in your integration — a disabled token cannot be re-enabled.
{
"error": {
"message": "The API token has been disabled. Generate a new token from Developer Tools > API in the GoSearch dashboard.",
"code": 401,
"type": "not_authorized"
}
}
The GoSearch API is REST-based and uses standard HTTP verbs and status codes. The API accepts JSON-encoded request bodies and returns JSON-encoded responses. All requests should be made over SSL.
The base URL to access the GoSearch API is https://api.gosearch.ai. For example, to access the Documents endpoint, just add the endpoint to the base URL: https://api.gosearch.ai/documents.
All responses from the API will include a standard HTTP successful or error status code. The successful status codes are as follows:
| HTTP Status Code | Description |
|---|---|
| 200 OK | The request was successful.. |
| 201 Created | The resource has been successfully created. |
For errors, we include extra information as to why the request was not successful. The error response body will have the following format:
{
"error": {
"message": "Descriptive information about the error",
"code": "HTTP error code",
"type": "Type of error returned"
}
}
For example, if you try to create a data source that already exists, you will get the following error response:
{
"error": {
"message": "The data source name Slack already exists. Please use another name for the data source.",
"code": 409,
"type": "conflict"
}
}
The error status codes, along with their error types, are as follows:
| HTTP Status Code | Error Type | Description |
|---|---|---|
| 400 Bad Request | bad_request | The request cannot be accepted. Might be because the request body is empty when it shouldn’t be. |
| 401 Unauthorized | not_authorized | The access token provided is invalid or deactivated. |
| 404 Not Found | not_found | The resource was not found. |
| 405 Method Not Allowed | method_not_allowed | The request method is not allowed for the endpoint. |
| 409 Conflict | conflict | The request conflicts with an existing resource. For example, if creating a data source with an existing name, this error will be returned. |
| 415 Unsupported Media Type | invalid_content_type | The request content type is not supported. |
| 422 Unprocessable Entity | invalid_request | The contents of the request contains errors, such as required fields that are missing or validation errors. |
| 429 Too Many Requests | rate_limit_exceeded | The rate limit has been exceeded. You have to wait a short time before trying again. |
| 500 Internal Server Error | internal_server_error | Something went wrong with the GoSearch API. |
A rate limit is enforced for every endpoint and is based on the company. It's important to note that creating multiple API tokens will not increase the overall rate limit. Different types of APIs are subject to different rate limits. If you exceed the rate limit, you will receive a 429 status code with the following error body:
{
"error": {
"message": "API rate limit exceeded. Please try again in 60 seconds.",
"code": 429,
"type": "rate_limit_exceeded"
}
}
Every request contains information about the rate limit in the HTTP response headers.
| HTTP Header | Description |
|---|---|
| RateLimit-Limit | The maximum number of requests allowed per minute for the endpoint. |
| RateLimit-Remaining | The number of requests remaining for the current rate limit window. |
| RateLimit-Reset | The number of seconds to wait until the rate limit window resets. This header will only be sent if the rate limit has been exceeded. |
All the endpoints that return a list come with a metadata object that contains pagination information. We return a default of 10 results per page and use the limit and offset parameters to determine the number of results to return and the number of results to skip. You can fetch the next set of results through the URL that is provided in metadata.links.next. If there are no more results, then the value will be null. The metadata object will include the following parameters. The dot notation denotes a child attribute.
| Pagination Parameters | Description |
|---|---|
| limit | The limit on the number of results to return, between 1 and 100. Defaults to 10 results. |
| offset | The number of results to skip. Defaults to 0. |
| count | The number of results returned in the current page. |
| total_results | The total number of results found. |
| links.next | The URL link to the next set of results. If there are no more results, this will be null. |
| links.prev | The URL link to the previous set of results. If there are no more results, this will be null. |
If you have any questions about the API or are running into errors, please reach out to support@gosearch.ai.