Timber.io API (v13.6.2)

Download OpenAPI specification:Download

Timber.io is a cloud-based logging service. The Timber API provides programmatic access to your logs and account.

REST

The Timber API is organized around the REST design pattern. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors.

GraphQL

Timber offers a fully functional GraphQL interface with queries and mutations. Everything you can do within our REST API you can do in our GraphQL API. The "Authentication" section below applies to both the REST and GraphQL interfaces.

Endpoint: https://api.timber.io/graphql.

Dates And Times

All dates and times will be formatted in the ISO 8601 format in the UTC time zone. Your date / time should have a Z qualifier at the end denoting this.

Errors

All errors returned by the Timber API will use the appropriate HTTP response code. For further clarification:

  • 401 - Authentication error. The provided Authorization header token is invalid, verify that your token is valid.
  • 403 - Authorization error. You do not have access to perform that action. See "Authorization" below.
  • 422 - Validation error indicating the supplied parameters and request body were invalid. Correct the errors and retry.
  • 500 - Internal server error. Indicates an unexpected error on Timber's end.

All other HTTP status codes follow the HTTP specification.

Each endpoint will document the error responses you can expect.

Support

As always, don't hesitate to contact us for help. You can reach us at [email protected].

Authentication

Timber's API requires an Authorization header. We support both the Basic and Bearer strategies:

Bearer

The Bearer strategy is preferred since it does not require an extra Base64 encoding step:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Basic

The Basic strategy should be used where you must include the API key as part of the URL:

https://user:636_87885d2353ea6675:c[email protected]logs.timber.io/sources/:source_id.frames

Notice the user: prefix! This is required for basic authentication. Timber will discard whatever you supply for the user value. The above results in the following header:

Authorization: Basic dXNlcjo2MzZfODc4ODVkMjM1M2VhNjY3NTpjOTAzZGQwMWI2ZmE3ZTYzMjgzMWE0YzM1MjI0MmFjYzk4ZmJhOTA5NzFlYTVlYTI5MTc3MjVjYzNmMzNlY2I0

Notice that the API key is Base64 encoded.

More info

For more information:

Authorization

Please see the RBAC docs

API Keys

Create A API Key

post /api_keys
Production API
https://api.timber.io/api_keys
Staging API
https://api.timber-staging.io/api_keys

Create an API key

This can be used to authenticate against the Timber API (see the "Authentication" section in the intro). This API key grants full access to all resources for the associated organization.

Request Body schema: application/json
name
required
string
organization_id
required
integer
description
string
tags
Array of string

Responses

201

Success Response

422

Validation Failed Response

Request samples

application/json
Copy
Expand all Collapse all
{
  • "tags":
    [
    ],
  • "organization_id": 0,
  • "name": "string",
  • "description": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "tags":
    [
    ],
  • "organization_id": "string",
  • "organization":
    {
    },
  • "name": "string",
  • "inserted_at": "2019-05-15T19:02:58Z",
  • "id": "string",
  • "description": "string",
  • "access_token": "string"
}

List All API Keys

get /api_keys
Production API
https://api.timber.io/api_keys
Staging API
https://api.timber-staging.io/api_keys

Query all API keys

query Parameters
organization_id
required
string
name
string
include
string

Used to include a single nested document. Specify the key to include.

includes
Array of string

Used to include nested documents (plural). Specify the keys to include.

limit
integer

Default: "100"

ids
Array of string
name_like
string
id
string
sort
string
Enum:"ID_ASC" "ID_DESC" "NAME_ASC" "NAME_DESC"


Descriptions:
* ID_ASC - Sort by ID ascending
* ID_DESC - Sort by ID descending
* NAME_ASC - Sort by name ascending
* NAME_DESC - Sort by name descending

tag
string
tags
Array of string

Responses

200

Success Response

422

Validation Failed Response

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ]
}

Update A API Key

put /api_keys/:id
Production API
https://api.timber.io/api_keys/:id
Staging API
https://api.timber-staging.io/api_keys/:id

Updated an API key

This will not change the token or invalidate the API key. This endpoint is used specifically to update metadata about the API key, such as it's name, description, and tags.

Request Body schema: application/json
id
required
string
name
required
string
description
string
tags
Array of string

Responses

200

Success Response

422

Validation Failed Response

Request samples

application/json
Copy
Expand all Collapse all
{
  • "tags":
    [
    ],
  • "name": "string",
  • "id": "string",
  • "description": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "tags":
    [
    ],
  • "organization_id": "string",
  • "organization":
    {
    },
  • "name": "string",
  • "inserted_at": "2019-05-15T19:02:58Z",
  • "id": "string",
  • "description": "string",
  • "access_token": "string"
}

Retrieve A API Key

get /api_keys/:id
Production API
https://api.timber.io/api_keys/:id
Staging API
https://api.timber-staging.io/api_keys/:id

Query one API key

query Parameters
id
string

Responses

200

Success Response

422

Validation Failed Response

Response samples

application/json
Copy
Expand all Collapse all
{
  • "tags":
    [
    ],
  • "organization_id": "string",
  • "organization":
    {
    },
  • "name": "string",
  • "inserted_at": "2019-05-15T19:02:58Z",
  • "id": "string",
  • "description": "string",
  • "access_token": "string"
}

Delete A API Key

delete /api_keys/:id
Production API
https://api.timber.io/api_keys/:id
Staging API
https://api.timber-staging.io/api_keys/:id

Delete an API key

This will immediately invalidate the API key, all subsequent requests will be denied.

Request Body schema: application/json
id
required
string

Responses

204

Success Response

422

Validation Failed Response

Request samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "tags":
    [
    ],
  • "organization_id": "string",
  • "organization":
    {