GoSearch API Documentation (1.1.0)

Introduction

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.

Authentication

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.

How to use your Access Token

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"
  }
}

API Overview

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.

Data Access

API requests don't have access to private data, such as documents from personal connectors.

Base URL

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.

Errors

All responses from the API will include a standard HTTP successful or error status code. The successful status codes are as follows:

HTTP Status CodeDescription
200 OKThe request was successful..
201 CreatedThe 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 CodeError TypeDescription
400 Bad Requestbad_requestThe request cannot be accepted. Might be because the request body is empty when it shouldn’t be.
401 Unauthorizednot_authorizedThe access token provided is invalid or deactivated.
404 Not Foundnot_foundThe resource was not found.
405 Method Not Allowedmethod_not_allowedThe request method is not allowed for the endpoint.
409 ConflictconflictThe 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 Typeinvalid_content_typeThe request content type is not supported.
422 Unprocessable Entityinvalid_requestThe contents of the request contains errors, such as required fields that are missing or validation errors.
429 Too Many Requestsrate_limit_exceededThe rate limit has been exceeded. You have to wait a short time before trying again.
500 Internal Server Errorinternal_server_errorSomething went wrong with the GoSearch API.

Rate Limiting

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 HeaderDescription
RateLimit-LimitThe maximum number of requests allowed per minute for the endpoint.
RateLimit-RemainingThe number of requests remaining for the current rate limit window.
RateLimit-ResetThe number of seconds to wait until the rate limit window resets. This header will only be sent if the rate limit has been exceeded.

Pagination

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 ParametersDescription
limitThe limit on the number of results to return, between 1 and 100. Defaults to 10 results.
offsetThe number of results to skip. Defaults to 0.
countThe number of results returned in the current page.
total_resultsThe total number of results found.
links.nextThe URL link to the next set of results. If there are no more results, this will be null.
links.prevThe URL link to the previous set of results. If there are no more results, this will be null.

Support

If you have any questions about the API or are running into errors, please reach out to support@gosearch.ai.

Servers
/d/api