Parsable API Overview

The Parsable API consists of HTTP RPC calls. All calls should be POSTs, and all return data in JSON format. All calls must be made via SSL.

The method signature for all calls is https://api.parsable.net/api/MODULE See "API Address" in each module's documentation for correct URL. Example: https://api.parsable.net/api/jobs

REQUESTS

There are three required headers:

Authorization: Token <token> - See API Authentication below.
Accept: application/json
Wi-Thrift-Version: X.Y.Z - where X.Y.Z is the major.minor.patch version of the Parsable API you are targeting.

The body of the request is a JSON object.

Basic Format of the request:

{
	"method": "METHOD_NAME",
	"arguments": { ... }
}

Example:

{
	"method": "login",
	"arguments": {
		"email": "user@domain.com",
		"password": "abcd1234"
	}
}

The method name and arguments correspond to the functions and arguments described in this document.

RESPONSES

Basic format of the response

{
	"method": "METHOD_NAME",
	"result|exception": { ... }
}

Example:

{
	"method": "login",
	"result": {
		"success": {
			"authToken": "ABCD...7890",
			"currentUser": {
				"id": "123456778-1234-1234-1234-1234567890AB",
				"email": "user@domain.com",
				"name": "John Doe",
				"validatedAt": 0
			},
			"teamIdToTeamRole": {
				"123456778-1234-1234-1234-1234567890AC": [
					4,
					3,
					2,
					1
				]
			}
		}
	}
}

TYPES

Parsable uses Thrift for API code and documentation generation. A list of Thrift types can be found Here. To send and receive data in JSON, Thrift definitions must be converted. Below is a table showcasing commonly used type conversions:

Thrift Category	Thrift Type	JSON Example
Base Type	`i32`	1
Base Type	`i64`	10000000000
Base Type	`bool`	true
Base Type	`double`	3.14
Base Type	`string`	"Parsable"
Base Type (i32)	`enum`	For `ADMIN = 1`: 1 OR "1" OR "ADMIN" Note: When enum types are used as the key in a map, only "1" and "ADMIN" are acceptable
Container	`list<string>`	`["a", "b", "c"]`
Container	`set<string>`	`["a", "b", "c"]` (must be unique)
Container	`map<string, i32>`	`{"a": 1, "b": 2, "c": 3}`
Struct	user.User	`{"id": "123456778-1234-1234-1234-1234567890AB", "email": "user@domain.com", "name": "John Doe", "validatedAt": 0}`
Union	user.UserKey	`{"id": "123456778-1234-1234-1234-1234567890AB"}` OR `{"email": "user@domain.com}`

ERRORS

If there was an exception thrown that is defined in the method definition

{
    "method": "login",
    "result": {
        "err": {
            "errorCode": 401,
            "message": "Invalid email or password"
        }
    }
}

For all other errors:

{
    "method": "loginUser",
    "exception": {
        "message": "Unknown function loginUser",
        "type": 1
    }
}

API Authentication

There are two categories of tokens in the Parsable system, Standard Tokens and Persistent Tokens. In both cases, the authentication token is a JWT-encoded token of the form eyJhbG...eyJpY... (it will be around 250-300 characters long).

The token must be passed in the request's Authorization header in this format: Token eyJhbG...eyJpY...

Standard Tokens
When users log into the Parsable systems normally, a user token is obtained via the authentication service. This token will expire after 30 days.
Persistent Tokens
Persistent tokens are generally associated with a system user created on a team and are intended for use by automated systems. Contact Parsable to allocate a persistent token for this usage, or to expire a token that is no longer in use.