---
updatedAt: 2025-05-12T20:32:28.000Z
agentTools:
  projectIndex: https://gainfully.readme.io/llms.txt
---

# Getting Started

The Gainfully API provides programmatic access to the data in our system. For example, a `Relationships` endpoint to retrieve a list of members in your organization or `Events` endpoints to fetch shared content.

## Authentication

To access Gainfully API, a API key is required in the HTTPS Authorization header.

```shell
curl --location --request GET 'https://api.gainfully.com/v1.0/relationships/' \
--header 'Content-Type: application/json' \
--header 'Authorization: API_KEY'
```

## Retrieving resources

The Gainfully API offers predictable and resource-oriented URLs.  A single resource is accessed by a unique identifier of an object `GET /example-resource/:id` while a list of resources is fetched by resource type `GET /example-resource/`.

### Ordering

Sorting is possible when retrieving resources by using the `ordering` query parameter.\
Any attributes of the resource can be used when sorting the response. To reverse the sorting order, the attribute name must be preceded by `-`

* Example: `GET /v1.0/content?ordering=name` (Resource objects are sorted by name in alphabetical order)
* Example: `GET /v1.0/content?ordering=-name` (Resource objects are sorted by name in reverse alphabetical order)

### Pagination

When retrieving multiple resource objects, the result is always paginated.

The Gainfully API uses the limit and offset pagination model where the limit represents the number of objects retrieved per page, while the offset indicates the starting position of the query in relation to the complete set of unpaginated items.

Paginated responses provide urls for the next and previous pages where available, as well as a total number of objects. ( See `Multiple resource response` for the response format )

The pagination parameters are:

* `limit`: Number of objects to retrieve in the response.
* `offset`: Starting position of the query in relation to the complete set of unpaginated items.

### Filtering

Resources support filtering by certain attributes ( documented for each resource ), which allow for easier fetching of desired resources, and filters are given in the URL as query parameters.

Filter parameter names are formed by prefixing `filter__` to the field name.

* Example: `GET /v1.0/relationships?filter__type=4`

Certain filters allow for operators through the `__` symbol. For example, timestamps can allow for relational operators.

* Example: `GET /v1.0/content?filter__created_at__gt=1572274684`

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Operator
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        gt
      </td>

      <td>
        greater than
      </td>
    </tr>

    <tr>
      <td>
        lt
      </td>

      <td>
        less than
      </td>
    </tr>
  </tbody>
</Table>

### Sparse fieldsets

When retrieving resource objects, it is possible to request only specific fields by using the `fields` parameter. This parameter takes a value of comma-separated field names.

* Example: `GET /v1.0/content?fields=name,message`

## Document Structure

### Single resource response

Retrieving a resource by a specific `id` will yield a single resource object.

The top-level document contains all attributes of the resource object. This includes the `id` attribute that uniquely identifies the object unless stated otherwise.

### Multiple resource response

Retrieving multiple resources yields a paginated list of resource objects.

The top level of the document contains the following attributes:

* `count`: Total number of resources
* `next`: URL for the next page of resources ( if available )
* `previous`: URL for the previous page of resources ( if available )
* `results`: List of resource objects. The resource objects inside the list follow the same structure from the `Single resource response` section.

## Error response

Errors have a specific document structure which is accompanied by an appropriate HTTP code to allow for easier error handling.

Resources have their specific error codes documented inside their documentation pages.\
An error response contains the following attributes:

* `field`: Attribute name inside the body of a request which caused the error - `error_code`: String-based code for the error
* `detail`: Description of the error

```http HTTP
{
    "field": "name",
    "error_code": "required",
    "detail": "This field is required."
}
```

## Rate limiting

The rate limiting of the API is done on a per-token basis. When the rate limit is reached, the following response is returned:

```http
Status: 429 Too Many Requests
{
  "field": null,
  "error_code": "throttled",
  "detail": "Request was throttled. Expected available in x seconds."
}
```