Aleph API Documentation (3.2.11)

Download OpenAPI specification:Download

Aleph is a powerful tool for people who follow the money. It helps investigators to securely access and search large amounts of data - no matter whether they are a government database or a leaked email archive.

General Overview

The Aleph web interface is powered by a Flask HTTP API. Aleph supports an extensive API for searching documents and entities. It can also be used to retrieve raw metadata, source documents and other useful details. Aleph's API tries to follow a pragmatic approach based on the following principles:

  • All API calls are prefixed with an API version; this version is /api/2/.
  • Responses and requests are both encoded as JSON. Requests should have the Content-Type and Accept headers set to application/json.
  • The application uses Representational State Transfer (REST) principles where convenient, but also has some procedural API calls.
  • The API allows API Authorization via an API key or JSON Web Tokens.

Authentication and Authorization

By default, any Aleph search will return only public documents in responses to API requests. If you want to access documents which are not marked public, you will need to sign into the tool. This can be done through the use on an API key. The API key for any account can be found by clicking on the "Profile" menu item in the navigation menu.

The API key must be sent on all queries using the Authorization HTTP header:

Authorization: ApiKey 363af1e2b03b41c6b3adc604956e2f66

Alternatively, the API key can also be sent as a query parameter under the api_key key.

Similarly, a JWT can be sent in the Authorization header, after it has been returned by the login and/or OAuth processes. Aleph does not use session cookies or any other type of stateful API.

Alerts API

Create and manage alerts.

List alerts

Returns a list of alerts for the user.

Responses

200

OK

get /alerts
https://data.occrp.org/api/2/alerts

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "results":
    [
    ],
  • "limit": 0,
  • "next": null,
  • "offset": 0,
  • "page": 0,
  • "pages": 0,
  • "previous": null,
  • "status": "string",
  • "total": 0,
  • "total_type": "string"
}

Create an alert

Creates an alert for a given query string.

Request Body schema: application/json
query
required
string

Responses

200

OK

post /alerts
https://data.occrp.org/api/2/alerts

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "query": "putin"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "created_at": "string",
  • "id": "string",
  • "links":
    {
    },
  • "normalized": "string",
  • "query": "string",
  • "updated_at": "string",
  • "writable": true
}

Delete an alert

Delete the alert with id alert_id

path Parameters
alert_id
required
integer >= 1
Example: 2

The alert ID.

Responses

204

No Content

delete /alerts/{alert_id}
https://data.occrp.org/api/2/alerts/{alert_id}

Fetch an alert

Return the alert with id alert_id

path Parameters
alert_id
required
integer >= 1
Example: 2

The alert ID.

Responses

200

OK

get /alerts/{alert_id}
https://data.occrp.org/api/2/alerts/{alert_id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "created_at": "string",
  • "id": "string",
  • "links":
    {
    },
  • "normalized": "string",
  • "query": "string",
  • "updated_at": "string",
  • "writable": true
}

Archive API

Download blobs from the archive.

Download a blob from the archive

Downloads a binary blob from the blob storage archive.

query Parameters
claim
integer

authorization token for an archive blob

Responses

200

OK

get /archive
https://data.occrp.org/api/2/archive

Collections API

Create and manage collections.

List collections

Returns a list of collections matching a given query. Returns all the collections accessible by a user if no query is given.

Responses

200

OK

get /collections
https://data.occrp.org/api/2/collections

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "facets": { },
  • "results":
    [
    ],
  • "limit": 0,
  • "next": null,
  • "offset": 0,
  • "page": 0,
  • "pages": 0,
  • "previous": null,
  • "status": "string",
  • "total": 0,
  • "total_type": "string"
}

Create a collection

Create a collection with the given metadata

Request Body schema: application/json
casefile
boolean
category
string <category>
countries
Array of strings <country>
data_url
null or string
foreign_id
string
info_url
null or string
label
required
string [ 2 .. 500 ] characters
languages
Array of strings <language>
publisher
null or string
publisher_url
null or string
summary
null or string

Responses

200

OK

post /collections
https://data.occrp.org/api/2/collections

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "casefile": true,
  • "category": "string",
  • "countries":
    [
    ],
  • "data_url": null,
  • "foreign_id": "string",
  • "info_url": null,
  • "label": "string",
  • "languages":
    [
    ],
  • "publisher": null,
  • "publisher_url": null,
  • "summary": null
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "casefile": true,
  • "category": "string",
  • "collection_id": "string",
  • "count": 0,
  • "countries":
    [
    ],
  • "created_at": "string",
  • "creator": { },
  • "foreign_id": "string",
  • "id": "string",
  • "kind": "string",
  • "label": "string",
  • "links":
    {
    },
  • "schemata": { },
  • "secret": true,
  • "team": { },
  • "updated_at": "string",
  • "writable": true
}

Delete a collection

Delete the collection with id collection_id

path Parameters
collection_id
required
integer >= 1

The collection ID.

Responses

204

No Content

delete /collections/{collection_id}
https://data.occrp.org/api/2/collections/{collection_id}

Get a collection

Return the collection with id collection_id

path Parameters
collection_id
required
integer >= 1

The collection ID.

Responses

200

OK

get /collections/{collection_id}
https://data.occrp.org/api/2/collections/{collection_id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "casefile": true,
  • "category": "string",
  • "collection_id": "string",
  • "count": 0,
  • "countries":
    [
    ],
  • "created_at": "string",
  • "creator": { },
  • "foreign_id": "string",
  • "id": "string",
  • "kind": "string",
  • "label": "string",
  • "links":
    {
    },
  • "schemata": { },
  • "secret": true,
  • "team": { },
  • "updated_at": "string",
  • "writable": true
}

Load entities into a collection

Bulk load entities into the collection with id collection_id

path Parameters
collection_id
required
integer >= 1

The collection ID.

query Parameters
unsafe
boolean

This will disable checksum security measures in order to allow bulk loading of document data.

Request Body schema: application/json

Entities to be loaded.

Array
schema
required
string <schema>
properties
object

Responses

204

No Content

post /collections/{collection_id}/bulk
https://data.occrp.org/api/2/collections/{collection_id}/bulk

Request samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Upload a document to a collection

Upload a document to a collection with id collection_id

path Parameters
collection_id
required
integer
Request Body schema: multipart/form-data
document
string <binary>

The document to upload

meta
object (DocumentCreateSchema)

Responses

200

OK

post /collections/{collection_id}/ingest
https://data.occrp.org/api/2/collections/{collection_id}/ingest

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "status": "string"
}

Load mappings for a collection

Load the mapping for the collection with id collection_id

path Parameters
collection_id
required
integer >= 1

The collection ID.

Request Body schema: application/json

The mapping to apply.

Responses

202

Accepted

post /collections/{collection_id}/mapping
https://data.occrp.org/api/2/collections/{collection_id}/mapping

Request samples

Content type
application/json
Copy
Expand all Collapse all
{ }

Get permissions for a collection

Get the list of all permissions for the collection with id collection_id

path Parameters
collection_id
required
integer

Responses

200

OK

get /collections/{collection_id}/permissions
https://data.occrp.org/api/2/collections/{collection_id}/permissions

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "results":
    [
    ],
  • "total": 0
}

Update permissions for a collection

Update permissions for the collection with id collection_id

path Parameters
collection_id
required
integer
Request Body schema: application/json
Array
read
boolean
role_id
integer
write
boolean

Responses

200

OK

post /collections/{collection_id}/permissions
https://data.occrp.org/api/2/collections/{collection_id}/permissions

Request samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Response samples

Content type
application/json
Copy
Expand all