numi api documentation¶
Overview¶
Format¶
All response bodies are sent as JSON values.
Where specified, query string parameters can be provided.
Request bodies for POST
, PUT
, PATCH
and DELETE
requests are expected to be valid JSON values.
Verbs¶
Unless otherwise specified, the following verbs are used for requests:
Verb | Description |
---|---|
GET | Used for retrieving a resource |
POST | Used for creating a resource |
PUT | Used to replace a resource |
PATCH | Used to partially update a resource with fields given in the request body |
DELETE | Used to delete a resource |
Partial updates¶
Partial update requests should provide instructions for how a resource should be modified according to the structure proposed in RFC 6902. Note that partial updates are atomic, so if any of the given instructions fail, none of the instructures will be carried out.
PATCH /projects/23/dialogues/21 HTTP/1.1
Content-Type: application/json-patch+json
[{
"op": "remove",
"path": "/sequences/0"
}, {
"op": "add",
"path": "/sequences",
"value": {
"id": "start",
"title": "Start of sequence",
"blocks": []
}
}]
Client errors¶
All client error responses contain a type
, message
and details
fields. type
is a programmitically-usable string representing the type of
the error, message
is a human-readable string describing the error and
details
is an object containing data specific to the error type.
HTTP/1.1 400 Bad Request
{
"type": "parse_error",
"message": "Invalid JSON in request body",
"details": {
"reason": "Expecting value",
"line": 1,
"column": 9
}
}
Two client errors common to API endpoints expecting a request body are parsing errors and validation errors.
Parsing errors¶
If the data provided in the request body is invalid JSON, a 400 Bad Request
response will be given.
The details
object contains a human readable reason
string describing why parsing failed, as well as the line
and column
numbers for where parsing failed.
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"type": "parse_error",
"message": "Invalid JSON in request body",
"details": {
"reason": "Expecting value",
"line": 1,
"column": 9
}
}
Validation errors¶
If the data provided in the request body is valid JSON, but the data does not
fit the schema for that particular request body, a 422 Unprocessable Entity
response will be given.
The details
object contains an array of errors
detailing why validation
failed. Each error object contains a programmitically-usable type
string
representing the type of validation error, a path
JSON pointer string
pointing to where in the given object validation failed, and a human readable
message
string describing the error.
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"type": "validation_error",
"message": "Invalid request body",
"details": {
"errors": [{
"type", "required",
"path": "/foo/0/baz",
"message": "'quux' is a required property"
}, {
"type", "type",
"path": "bar",
"message": "23 is not of type 'string'"
}]
}
}
Read-only fields¶
Many of the API’s data structures return read-only fields in API responses. For example, API-generated id
fields, or a resource’s url
field. If read only fields are provided by clients in API request bodies, the way these are handled depends on the request method.
For PUT
requests, in order to allow clients to more easily send back an updated description, clients may include read-only fields, but these fields will be ignored when replacing the resource.
For POST
and PATCH
requests, if a client provides read-only fields, the API will return an 422 Unprocessable Entity
response, since this case is likely to be a client error:
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"type": "validation_error",
"message": "Invalid request body",
"details": {
"errors": [{
"type", "additionalProperties",
"path": "/",
"message": "Additional properties are not allowed ('id' was unexpected)"
}]
}
}
Concepts¶
Users¶
Users have access to a set of projects. Depending on their permissions, users can view or modify a project and its dialogues.
Projects¶
A project comprises a set of dialogues. End user state is shared across dialogues under the same project.
Dialogues¶
A dialogue comprises the entire set of steps to follow when a user interacts with a service. It contains a set of Sequences, each of which contain a set of Blocks.
Sequences¶
A sequence is a set of steps that follow one after the other, where each step corresponds to a Block. A user moves from one sequence to another if different steps need to be followed based on certain conditions.
For example, a dialogue could contain a sequence with a block that asks the user a multiple choice question and moves the user to a different sequence that corresponds to their choice.
Blocks¶
A block is a single step to follow when interacting with the user. This step may be, for example, a screen asking the user a question, or a step not visible to the user, for example, registering the user with a service.
Symbols¶
Symbols are used in a Dialogue data structure as programmatically-usable strings. Their main use is for identifying and referencing sequences, blocks and block types.
Revision¶
A revision represents a change or set of changes made to a dialogue. There are different revision types:
Edit¶
Applies a set of changes to a dialogue description. For example, changing the content in a block or changing the position of a block in a sequence.
Revert¶
Reverts a dialogue’s description back to its state at an earlier revision.
Releases¶
A release marks a point in a dialogue’s history of revisions. End users will always interact with the most recently published release’s corresponding dialogue description.
Channels¶
- A channel is an address a dialogue can use to interact with end users, for example:
- an sms shortcode (e.g.
2233
) - a USSD starcode (e.g.
*120*321#
) - a twitter handle (e.g.
@foo
)
- an sms shortcode (e.g.
Permissions¶
A user’s actions are limited by the permissions they have been granted. Users can be granted the following permissions:
admin
¶
Grants create, archive, read and write access for all projects and dialogues, and publish access for all dialogues.
projects:create
¶
Grants access to create new projects. Users with this permission obtain project:admin
access for the projects they create.
project:admin
¶
Grants create, archive, read, write and publish access for a given project’s dialogues.
project:dialogues:read
¶
Grants read access for a given project’s dialogues.
project:dialogues:write
¶
Grants write access for a given project’s dialogues.
dialogue:read
¶
Grants read access for a given dialogue.
dialogue:write
¶
Grants write access for a given dialogue.
Users¶
-
GET
/user
¶ Retrieves the description of the authenticated user.
GET /user HTTP/1.1
HTTP/1.1 200 OK Content-Type: application/json { "id": "0a2d19e0-bb10-4b84-98cc-52a82b6ed427", "url": "/users/1", "email": "foo@bar.org", "first_name": "Joan", "last_name": "Watson", "permissions": [{ "type": "admin" }] }
-
POST
/user/password-changes/
¶ Creates a password change request for the authenticated user using the details given in the request body.
POST /user/password-changes/ HTTP/1.1 Content-Type: application/json { "old_password": "1337", "new_password": "r00t" }
HTTP/1.1 204 No Content Content-Type: application/json
-
GET
/users/
¶ Retrieves the summaries of all users. Only accessible if the authenticated user has admin permission.
GET /user HTTP/1.1
HTTP/1.1 200 OK Content-Type: application/json [{ "id": "0a2d19e0-bb10-4b84-98cc-52a82b6ed427", "url": "/users/1", "email": "foo@bar.org", "first_name": "Joan", "last_name": "Watson" }]
Query Parameters: - page (number) – 1-based index of the page of users to show. Defaults to
1
. - per_page (number) – Number of users to show per page. Defaults to
30
. Maximum is100
.
- page (number) – 1-based index of the page of users to show. Defaults to
-
POST
/users/
¶ Creates a new user with the description given in the request body and returns the created user’s description, along with the generated
id
field andurl
field for accessing the user description.POST /projects/ HTTP/1.1 Content-Type: application/json { "first_name": "Joan", "last_name": "Watson", "password": "1337" }
HTTP/1.1 201 Created Content-Type: application/json { "id": "0a2d19e0-bb10-4b84-98cc-52a82b6ed427", "url": "/users/0a2d19e0-bb10-4b84-98cc-52a82b6ed427", "email": "foo@bar.org", "first_name": "Joan", "last_name": "Watson" }
-
GET
/users/
(str: user_id)¶ Retrieves the description of the user with id
user_id
.GET /users/0a2d19e0-bb10-4b84-98cc-52a82b6ed427 HTTP/1.1
HTTP/1.1 200 OK Content-Type: application/json { "id": "0a2d19e0-bb10-4b84-98cc-52a82b6ed427", "url": "/users/0a2d19e0-bb10-4b84-98cc-52a82b6ed427", "email": "foo@bar.org", "first_name": "Joan", "last_name": "Watson" }
-
PUT
/users/
(str: user_id)¶ Replaces the description of the user with id
user_id
with the description given in the request body and returns the given description, along with the user’sid
and theurl
for accessing the user’s description.This operation is only accessible to the authenticated user if their user id is
user_id
, or if they have admin permission.PUT /users/0a2d19e0-bb10-4b84-98cc-52a82b6ed427 HTTP/1.1 Content-Type: application/json { "first_name": "Joan", "last_name": "Watson" }
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "0a2d19e0-bb10-4b84-98cc-52a82b6ed427",
"url": "/users/0a2d19e0-bb10-4b84-98cc-52a82b6ed427",
"email": "foo@bar.org",
"first_name": "Joan",
"last_name": "Watson"
}
-
PATCH
/users/
(str: user_id)¶ Partially updates the description of the user with id
user_id
using the instructions given in the request body and returns the given user’s description, along with the user’sid
and theurl
for accessing the user’s description.This operation is only accessible to the authenticated user if their user id is
user_id
, or if they have admin permission.PATCH /users/0a2d19e0-bb10-4b84-98cc-52a82b6ed427 HTTP/1.1 Content-Type: application/json-patch+json [{ "op": "replace", "path": "/first_name", "value": "Joan" }]
HTTP/1.1 200 OK Content-Type: application/json { "id": "0a2d19e0-bb10-4b84-98cc-52a82b6ed427", "url": "/users/0a2d19e0-bb10-4b84-98cc-52a82b6ed427", "email": "foo@bar.org", "first_name": "Joan", "last_name": "Watson" }
-
POST
/password-resets/
¶ Creates a password reset request for the user with the email address provided in the request body.
If a user with the given email address is found, the user will be sent an email containing a link to be accessed in order to confirm the reset and choose a new password.
POST /password-resets/ HTTP/1.1 Content-Type: application/json { "email": "foo@bar.org" }
HTTP/1.1 204 No Content Content-Type: application/json
Note
To avoid leaking information on whether a user has a given email address, the
API will return a 204
response regardless of whether a user matches the
given email address or not.
-
POST
/password-confirmations/
¶ Confirms a password reset using the confirmation details given in the request body.
POST /password-confirmations/ HTTP/1.1 Content-Type: application/json { "token": "123abc", "password": "r00t" }
HTTP/1.1 204 No Content Content-Type: application/json
Permissions¶
-
GET
/users/
(str: user_id)/permissions/
¶ Retrieves the permissions accessible to the authenticating user for the user with id
user_id
.GET /users/0a2d19e0-bb10-4b84-98cc-52a82b6ed427/permissions/ HTTP/1.1
HTTP/1.1 200 OK Content-Type: application/json [{ "id": "9a12594f30220f6a91bde8da961505be", "type": "admin" }]
-
GET
/users/
(str: user_id)/permissions/
(str: permission_id)¶ Retrieves the permission with id
permission_id
for the user with iduser_id
.GET /users/0a2d19e0-bb10-4b84-98cc-52a82b6ed427/permissions/9a12594f30220f6a91bde8da961505be HTTP/1.1
HTTP/1.1 200 OK Content-Type: application/json { "id": "9a12594f30220f6a91bde8da961505be", "type": "admin" }
-
POST
/users/
(str: user_id)/permissions/
¶ Creates a new permission for the user with id
user_id
and returns the created permission.POST /users/0a2d19e0-bb10-4b84-98cc-52a82b6ed427/permissions/ HTTP/1.1 Content-Type: application/json { "type": "projects:admin", "details": { "project_id": "23" } }
HTTP/1.1 200 OK Content-Type: application/json { "id": "2294e0854d66b461eceddbf239f80f04", "type": "projects:admin", "details": { "project_id": "23" } }
-
DELETE
/users/
(str: user_id)/permissions/
(str: permission_id)¶ Revokes the permission with id
permission_id
for the user with iduser_id
and returns the revoked permission.DELETE /users/0a2d19e0-bb10-4b84-98cc-52a82b6ed427/permissions/2294e0854d66b461eceddbf239f80f04 HTTP/1.1
HTTP/1.1 200 OK Content-Type: application/json { "id": "2294e0854d66b461eceddbf239f80f04", "type": "projects:admin", "details": { "project_id": "23" } }
Projects¶
-
GET
/projects/
¶ Retrieves a summary of projects the authenticated user has access to.
GET /projects/ HTTP/1.1
HTTP/1.1 200 OK Content-Type: application/json [{ "id": "1", "title": "Maternal Health ZA", "url": "/projects/1" }, { "id": "2", "title": "Maternal Health MX", "url": "/projects/2", }]
Query Parameters: - page (number) – 1-based index of the page of projects to show. Defaults to
1
. - per_page (number) – Number of projects to show per page. Defaults to
30
. Maximum is100
.
- page (number) – 1-based index of the page of projects to show. Defaults to
-
GET
/projects/
(str: project_id)¶ Retrieves the description of the project with id
project_id
.GET /projects/23 HTTP/1.1
HTTP/1.1 200 OK Content-Type: application/json { "id": "23", "title": "Maternal Health ZA" "url": "/projects/23", "is_archived": false, "dialogues": [{ "id": "21", "title": "Service Rating Survey", "url": "/projects/23/dialogues/21", "is_archived": false, "is_published": false, "has_changes": false, "can_view": true, "can_edit": true }] }
If the project isn’t found, a
404
response will be given. The response body’sdetails
object contains theid
of the project given in the request.HTTP/1.1 404 Not Found Content-Type: application/json { "type": "not_found", "message": "Project 23 not found", "details": {"id": "23"} }
-
POST
/projects/
¶ Creates a new project with the project description given in the request body and returns the created projects’s description, along with the generated dialogue
id
field andurl
field for accessing the project description.The authenticated user creating the project is given project admin access for the newly created project.
POST /projects/ HTTP/1.1 Content-Type: application/json { "title": "Maternal Health ZA", }
HTTP/1.1 201 Created Content-Type: application/json { "id": "23", "url": "/projects/23", "title": "Maternal Health ZA", "dialogues": [], "is_archived": false }
-
PUT
/projects/
(str: project_id)¶ Replaces the description of the project with id
project_id
with the description given in the request body and returns the given description, along with the projects’sid
and theurl
for accessing the projects’s description.PUT /projects/23 HTTP/1.1 Content-Type: application/json { "id": "23", "title": "Maternal Health ZA" }
HTTP/1.1 200 OK Content-Type: application/json { "id": "23", "title": "Maternal Health ZA" "url": "/projects/23", "is_archived": false, "dialogues": [{ "id": "21", "title": "Service Rating Survey", "url": "/projects/23/dialogues/21", "is_archived": false, "is_published": false, "has_changes": false, "can_view": true, "can_edit": true }] }
-
PATCH
/projects/
(str: project_id)/
¶ Partially updates the description of the project with id
project_id
with the instructions in the request body and returns the given description, along with the projects’sid
and theurl
for accessing the project’s description.
PATCH /projects/23 HTTP/1.1
Content-Type: application/json-patch+json
[{
"op": "replace",
"path": "/title",
"value": "Maternal Health ZA"
}]
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "23",
"title": "Maternal Health ZA"
"url": "/projects/23",
"is_archived": false,
"dialogues": [{
"id": "21",
"title": "Service Rating Survey",
"url": "/projects/23/dialogues/21",
"is_archived": false,
"is_published": false,
"has_changes": false,
"can_view": true,
"can_edit": true
}]
}
-
GET
/projects/
(str: project_id)/channels/
¶ Retrieves the descriptions of the channels accessible to the project with the id
project_id
.Only accessible if the authenticated user has admin permission or has permissions associated with project
project_id
.GET /projects/21/channels/ HTTP/1.1
HTTP/1.1 200 OK Content-Type: application/json [{ "id": "23", "url": "/channels/23", "project_id": "21", "title": "@foo", "address": "@foo", "type": "twitter", "is_available": true, "provider": { "id": "21", "title": "Twitter" } }]
Dialogues¶
-
GET
/projects/
(str: project_id)/dialogues/
¶ Retrieves a summary of every dialogue contained in the project with id
project_id
.GET /projects/23/dialogues/ HTTP/1.1
HTTP/1.1 200 OK Content-Type: application/json [{ "id": "21", "title": "Service Rating Survey", "url": "/projects/23/dialogues/21", "is_archived": false, "is_published": false, "has_changes": false, "can_view": true, "can_edit": true }]
Query Parameters: - is_archived (boolean) – Filter on whether this dialogue has been archived.
- is_published (boolean) – Filter on whether this dialogue has been published.
- has_changes (boolean) – Filter on whether this dialogue has unpublished changes or not.
- can_view (boolean) – Filter on whether the user can view this dialogue or not.
- can_edit (boolean) – Filter on whether the user can edit this dialogue or not.
-
GET
/projects/
(str: project_id)/dialogues/
(str: dialogue_id)¶ Retrieves the description of the dialogue with id
dialogue_id
in the project with idproject_id
.GET /projecs/23/dialogues/21 HTTP/1.1
HTTP/1.1 200 OK Content-Type: application/json { "id": "21", "title": "Service Rating Survey", "sequences": [], "is_archived": false, "is_published": false, "has_changes": false, "can_view": true, "can_edit": true }
If the dialogue isn’t found, a
404
response will be given. The response body’sdetails
object contains theid
given in the request.HTTP/1.1 404 Not Found Content-Type: application/json { "type": "not_found", "message": "Dialogue 21 not found", "details": {"id": "21"} }
-
POST
/projects/
(str: project_id)/dialogues/
¶ Creates a new dialogue under the project with the id
project_id
using the dialogue description given in the request body and returns the created dialogue’s description, along with the generated dialogueid
field andurl
field for accessing the dialogue description.POST /projects/23/dialogues/ HTTP/1.1 Content-Type: application/json { "title": "Service Rating Survey", "sequences": [] }
HTTP/1.1 201 Created Content-Type: application/json { "id": "21", "url": "/projects/23/dialogues/21", "title": "Service Rating Survey", "sequences": [], "is_archived": false, "is_published": false, "has_changes": false, "can_view": true, "can_edit": true }
-
PUT
/projects/
(str: project_id)/dialogues/
(str: dialogue_id)¶ Replaces the description of the dialogue with id
dialogue_id
in the project with idproject_id
with the description given in the request body and returns the given description, along with the dialogue’sid
and theurl
for accessing the dialogue’s description.Replacing the dialogue creates a new edit revision with a JSON patch representing the instructions needed to change the current dialogue description to the new description given in the request body.
POST /projects/23/dialogues/21 HTTP/1.1 Content-Type: application/json { "title": "Service Rating Survey", "sequences": [], "is_archived": false }
HTTP/1.1 200 OK Content-Type: application/json { "id": "21", "url": "/projects/23/dialogues/21", "title": "Service Rating Survey", "sequences": [], "is_archived": false, "is_published": false, "has_changes": false, "can_view": true, "can_edit": true }
Warning
If the id
of a sequence or block is changed, the API will regard the changed sequence or block as a new entity. This means all state previously associated to the sequence or block (for example, metrics and translations) will no longer be associated with it.
-
PATCH
/projects/
(str: project_id)/dialogues/
(str: dialogue_id)¶ Partially updates the description of the dialogue with id
dialogue_id
in the project with idproject_id
with the instructions in the request body and returns the given description, along with the dialogue’sid
and theurl
for accessing the dialogue’s description.Partially updating the dialogue creates a new edit revision using the provided patch instructions.
PATCH /projects/23/dialogues/21 HTTP/1.1
Content-Type: application/json-patch+json
[{
"op": "remove",
"path": "/sequences/0"
}, {
"op": "add",
"path": "/sequences",
"value": {
"id": "start",
"title": "Start of sequence",
"blocks": []
}
}]
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "21",
"url": "/projects/23/dialogues/21",
"title": "Service Rating Survey",
"sequences": [{
"id": "start",
"title": "Start of sequence",
"blocks": []
}],
"is_archived": false,
"is_published": false,
"has_changes": false,
"can_view": true,
"can_edit": true
}
Warning
If the id
of a sequence or block is changed, the API will regard the changed sequence or block as a new entity. This means all state previously associated to the sequence or block (for example, metrics and translations) will no longer be associated with it.
Archiving dialogues¶
A dialogue can be archived by setting is_archived
to true
when replacing or partially updating the dialogue description. The dialogue is still accessible via the api, but will no longer be triggered by any events associated to it.
Revisions¶
-
GET
/projects/
(str: project_id)/dialogues/
(str: dialogue_id)/revisions/
¶ Retrieves the revisions of dialogue
dialogue_id
in the projectproject_id
.GET /projects/23/dialogues/21/revisions/ HTTP/1.1
HTTP/1.1 200 OK Content-Type: application/json [{ "id": "1", "number": 1, "user_id": "17", "created": 1459943775033, "type": "edit", "details": { "id": "start", "title": "Start of sequence", }, "properties": { "edit_type": "new_sequence", "patch": [{ "op": "add", "path": "/sequences", "value": { "id": "start", "title": "Start of sequence", "blocks": [] } }] } }]
Query Parameters: - page (number) – 1-based index of the page of revisions to show. Defaults to
1
. - per_page (number) – Number of revisions to show per page. Defaults to
30
. Maximum is100
. - ordering (string) – The ordering of the returned revisions. If multiple
ordering
parameters are provided, the returned revisions will be sorted by each provided parameter, in the order the parameters were specified. Defaults to-number
.
- page (number) – 1-based index of the page of revisions to show. Defaults to
Ordering revisions¶
Parameter | Description |
---|---|
number |
Return revisions in ascending order of revision number |
-number |
Return revisions in descending order of revision number |
created |
Return revisions in ascending order of creation date |
-created |
Return revisions in descending order of creation date |
-
POST
/projects/
(str: project_id)/dialogues/
(str: dialogue_id)/revisions/
¶ Creates a new revision for dialogue
dialogue_id
under projectproject_id
using the description given in the request body and returns the created revisions’s description, along with the generatedid
field andurl
field for accessing the revision description.Creating a new revision updates the dialogue’s description. Any new requests to retrieve the dialogue will return a dialogue description with the new revision applied.
POST /projects/23/dialogues/21/revisions/ HTTP/1.1 Content-Type: application/json { "type": "edit", "details": { "id": "start", "title": "Start of sequence", }, "properties": { "edit_type": "new_sequence", "patch": [{ "op": "add", "path": "/sequences", "value": { "id": "start", "title": "Start of sequence", "blocks": [] } }] } }
HTTP/1.1 201 Created Content-Type: application/json { "id": "1", "number": 1, "user_id": "17", "created": 1459943775033, "type": "edit", "details": { "id": "start", "title": "Start of sequence", }, "properties": { "edit_type": "new_sequence", "patch": [{ "op": "add", "path": "/sequences", "value": { "id": "start", "title": "Start of sequence", "blocks": [] } }] } }
It is also possible to create revisions in bulk by providing an array of revisions. In this case, an array of revision descriptions will be returned:
POST /projects/23/dialogues/21/revisions/ HTTP/1.1 Content-Type: application/json [{ "type": "edit", "details": { "id": "start", "title": "Start of sequence", }, "properties": { "edit_type": "new_sequence", "patch": [{ "op": "add", "path": "/sequences", "value": { "id": "start", "title": "Start of sequence", "blocks": [] } }] } }, { "type": "edit", "details": { "id": "start", "old_title": "Start of sequence", "new_title": "Start" }, "properties": { "edit_type": "rename_sequence", "patch": [{ "op": "add", "path": "/sequences/title", "value": "Start" }] } }]
HTTP/1.1 201 Created Content-Type: application/json [{ "id": "1", "number": 1, "user_id": "17", "created": 1459943775033, "type": "edit", "details": { "id": "start", "title": "Start of sequence", }, "properties": { "edit_type": "new_sequence", "patch": [{ "op": "add", "path": "/sequences", "value": { "id": "start", "title": "Start of sequence", "blocks": [] } }] } }, { "id": "2", "number": 2, "user_id": "17", "created": 1459943775033, "type": "edit", "details": { "id": "start", "old_title": "Start of sequence", "new_title": "Start" }, "properties": { "edit_type": "rename_sequence", "patch": [{ "op": "add", "path": "/sequences/title", "value": "Start" }] } }]
Note
Creating revisions in bulk is done atomically. If one of the given revisions cannot be created, none of the given revisions will be created.
Releases¶
-
GET
/projects/
(str: project_id)/dialogues/
(str: dialogue_id)/releases/
¶ Retrieves the descriptions of the releases of dialogue
dialogue_id
in the projectproject_id
.GET /projects/23/dialogues/21/releases/ HTTP/1.1
HTTP/1.1 200 OK Content-Type: application/json [{ "id": "1", "number": 1, "url": "/projects/23/dialogues/21/releases/1", "revision_id": "7" }]
Query Parameters: - page (number) – 1-based index of the page of releases to show. Defaults to
1
. - per_page (number) – Number of releases to show per page. Defaults to
30
. Maximum is100
. - ordering (string) – The ordering of the returned releases. If multiple
ordering
parameters are provided, the returned releases will be sorted by each provided parameter, in the order the parameters were specified. Defaults to-number
.
- page (number) – 1-based index of the page of releases to show. Defaults to
Ordering releases¶
Parameter | Description |
---|---|
number |
Return releases in ascending order of release number |
-number |
Return releases in descending order of release number |
created |
Return releases in ascending order of creation date |
-created |
Return releases in descending order of creation date |
-
GET
/projects/
(str: project_id)/dialogues/
(str: dialogue_id)/releases/
(str: release_id)¶ Retrieves the description for the release with id
release_id
for dialoguedialogue_id
contained in the project with idproject_id
.GET /projects/23/dialogues/21/releases/44 HTTP/1.1
HTTP/1.1 200 OK Content-Type: application/json { "id": "1", "number": 1, "url": "/projects/23/dialogues/21/releases/1", "revision_id": "7", "created": 1460022608855 }
If the release isn’t found, a
404
response will be given. The response body’sdetails
object contains theid
anddialogue_id
given in the request.HTTP/1.1 404 Not Found Content-Type: application/json { "type": "not_found", "message": "Release 44 not found", "details": { "id": "44", "dialogue_id": "21" } }
-
POST
/projects/
(str: project_id)/dialogues/
(str: dialogue_id)/releases/
¶ Creates a new release for dialogue
dialogue_id
under the project with the idproject_id
using the description given in the request body and returns the created releases’s description, along with the generated releaseid
field andurl
field for accessing the release description.POST /projects/23/dialogues/21/releases/ HTTP/1.1 Content-Type: application/json { "revision_id": "7" }
HTTP/1.1 201 Created Content-Type: application/json { "id": "1", "number": 1, "revision_id": "7", "created": 1460022608855, "url": "/projects/23/dialogues/21/releases/1" }
Channels¶
-
GET
/channels/
¶ Retrieves the descriptions of all channels. Only accessible if the authenticated user has admin permission.
GET /channels/ HTTP/1.1
HTTP/1.1 200 OK Content-Type: application/json [{ "id": "23", "url": "/channels/23", "project_id": "21", "title": "@foo", "address": "@foo", "type": "twitter", "is_available": true, "provider": { "id": "21", "title": "Twitter" } }]
-
GET
/channels/
(str: channel_id)¶ Retrieves the description of the channel with the id
channel_id
.Only accessible if the authenticated user has admin permission or has access to a project using the channel
channel_id
.GET /channels/23 HTTP/1.1
HTTP/1.1 200 OK Content-Type: application/json { "id": "23", "url": "/channels/23", "project_id": "21", "title": "@foo", "address": "@foo", "type": "twitter", "is_available": true, "provider": { "id": "21", "title": "Twitter" } }
-
PUT
/channels/
(str: channel_id)¶ Replaces the description of the channel with id
channel_id
with the description given in the request body and returns the given description, along with the channel’sid
and theurl
for accessing the channel’s description.This operation is only accessible to the authenticated user if they have admin permission.
PUT /channels/23 HTTP/1.1 Content-Type: application/json { "id": "23", "project_id": "17", "url": "/channels/23", "title": "@foo", "address": "@foo", "type": "twitter", "is_available": true }
HTTP/1.1 200 OK Content-Type: application/json { "id": "23", "project_id": "17", "url": "/channels/23", "title": "@foo", "address": "@foo", "type": "twitter", "is_available": true }
-
PATCH
/channels/
(str: channel_id)¶ Partially updates the description of the channel with id
channel_id
using the instructions given in the request body and returns the given channel’s description, along with the channel’sid
and theurl
for accessing the channel’s description.This operation is only accessible to the authenticated user if they have admin permission.
PATCH /channels/23 HTTP/1.1 Content-Type: application/json-patch+json [{ "op": "replace", "path": "/project_id", "value": "17" }]
HTTP/1.1 200 OK Content-Type: application/json { "id": "23", "project_id": "17", "url": "/channels/23", "title": "@foo", "address": "@foo", "type": "twitter", "is_available": true }
Channel access¶
A channel can only be accessible by one project at a time. A channel can be made accessible to a project by setting project_id
to the project’s id when replacing or partially updating the channel description.
Providers¶
-
GET
/providers/
¶ Retrieves the summaries of all providers.
Only accessible if the authenticated user has admin permission.
GET /providers/ HTTP/1.1
HTTP/1.1 200 OK Content-Type: application/json [{ "id": "21", "url": "/providers/21", "title": "Twitter" }, { "id": "22", "url": "/providers/22", "title": "MTN Nigeria" }]
-
GET
/providers/
(str: provider_id)¶ Retrieves the description of the provider with the id
provider_id
.Only accessible if the authenticated user has admin permission or has access to a project using a channel associated with
provider_id
.GET /providers/21 HTTP/1.1
HTTP/1.1 200 OK Content-Type: application/json { "id": "21", "url": "/providers/21", "title": "Twitter" "channels": [{ "id": "23", "url": "/channels/23", "project_id": 21, "title": "@foo", "address": "@foo", "type": "twitter", "is_available": true }] }
Data Structures¶
Users¶
User¶
properties:
id:
type: string
readOnly: true
description: |
The user's identifier (generated by the API)
url:
type: string
readOnly: true
description: |
API url for accessing the user description.
email:
type: string
format: email
readOnly: true
description: |
The email address used when authenticating the user.
first_name:
type: string
description: |
The user's first name.
last_name:
type: string
description: |
The user's last name.
additionalProperties: false
User Summary¶
properties:
id:
type: string
readOnly: true
description: |
The user's identifier (generated by the API)
url:
type: string
readOnly: true
description: |
API url for accessing the user description.
email:
type: string
format: email
readOnly: true
description: |
The email address used when authenticating the user.
first_name:
type: string
readOnly: true
description: |
The user's first name.
last_name:
type: string
readOnly: true
description: |
The user's last name.
additionalProperties: false
New User¶
$ref: '#/definitions/user/user'
properties:
password:
type: string
description: |
The new user's password.
Password change¶
old_password:
type: 'string'
description: |
The user's old password.
new_password:
type: 'string'
description: |
The user's new password.
Password reset¶
email:
type: string
format: email
description: |
The email address for the user who's password to reset.
Password reset confirmations¶
token:
type: 'string'
description: |
Token emailed to the user for the password reset.
password:
type: 'string'
description: |
The user's new password.
Projects¶
Project¶
required:
- title
properties:
id:
type: string
readOnly: true
description: |
The projects's identifier (generated by the API)
url:
type: string
readOnly: true
description: |
API url for accessing the project description.
title:
type: string
description: |
The human-readable title of the project
is_archived:
type: boolean
default: false
description: |
Flag representing whether this project has been archived.
dialogues:
type: array
readOnly: true
items:
$ref: '#/definitions/dialogue/summary'
description: |
A summary of each dialogue contained in this project.
additionalProperties: false
Project Summary¶
properties:
id:
type: string
readOnly: true
description: |
The projects's identifier (generated by the API)
url:
type: string
readOnly: true
description: |
API url for accessing the project description.
title:
type: string
readOnly: true
description: |
The human-readable title of the project
is_archived:
type: boolean
readOnly: true
description: |
Flag representing whether this project has been archived.
additionalProperties: false
Dialogues¶
Dialogue¶
required:
- title
- sequences
properties:
id:
type: string
readOnly: true
description: |
The dialogue's identifier (generated by the API)
revision_id:
type: string
readOnly: true
description: |
Identifier of the revision associated with the dialogue description.
url:
type: string
readOnly: true
description: |
API url for accessing the dialogue description.
title:
type: string
description: |
The human-readable title of the dialogue
sequences:
type: array
items:
$ref: '#/definitions/dialogue/sequence'
description: |
The dialogue's set of sequences
is_archived:
type: boolean
default: false
description: |
Flag representing whether this dialogue has been archived.
is_published:
type: boolean
readOnly: true
description: |
Flag representing whether this dialogue has been published before.
has_changes:
type: boolean
readOnly: true
description: |
Flag representing whether this dialogue has unpublished changes.
can_view:
type: boolean
readOnly: true
description: |
Flag representing whether the authenticated user can view this dialogue.
can_edit:
type: boolean
readOnly: true
description: |
Flag representing whether the authenticated user can edit this dialogue.
additionalProperties: false
Dialogue Summary¶
properties:
id:
type: string
readOnly: true
description: |
The dialogue's identifier (generated by the API)
revision_id:
type: string
readOnly: true
description: |
Identifier of the revision associated with the dialogue description.
url:
type: string
readOnly: true
description: |
API url for accessing the dialogue description.
title:
type: string
readOnly: true
description: |
The human-readable title of the dialogue
is_archived:
type: boolean
readOnly: true
description: |
Flag representing whether this dialogue has been archived.
is_published:
type: boolean
readOnly: true
description: |
Flag representing whether this dialogue has been published before.
has_changes:
type: boolean
readOnly: true
description: |
Flag representing whether this dialogue has unpublished changes.
can_view:
type: boolean
readOnly: true
description: |
Flag representing whether the authenticated user can view this dialogue.
can_edit:
type: boolean
readOnly: true
description: |
Flag representing whether the authenticated user can edit this dialogue.
additionalProperties: false
Sequence¶
required:
- id
- title
- blocks
properties:
id:
$ref: '#/definitions/dialogue/symbol'
description: |
The sequence's identifier. Must be generated by the client.
title:
type: text
description: |
A human-readable title describing this sequence.
blocks:
type: array
items:
$ref: '#/definitions/dialogue/block'
description: |
The sequence's set of blocks
additionalProperties: false
Block¶
Note
A block’s properties
object is validated against a schema corresponding to the block’s type (represented by the type
field).
required:
- id
- type
properties:
id:
$ref: '#/definitions/dialogue/symbol'
description: |
The block's identifier. Must be generated by the client.
type:
$ref: '#/definitions/dialogue/symbol'
description: |
Identifies the type of block. Valid values depend on which block types
have been registered with a particular instance of the API.
title:
type: text
description: |
A human-readable title describing the block.
properties:
type: object
description: |
Properties relevant to the block's type. For example, a block that asks
the user a question may have a `question` property here.
additionalProperties: false
Symbol¶
type: string
pattern: '^[a-z][a-z0-9-]*$'
Revisions¶
Revision¶
required:
- patch
properties:
id:
type: string
readOnly: true
description: |
The revisions's identifier (generated by the API)
url:
type: string
readOnly: true
description: |
API url for accessing the revision description.
user_id:
type: string
readOnly: true
description: |
The identifier for the user who created this revision.
number:
type: number
readOnly: true
description: |
The revision's number, starting at `1` for the first revision, and
incremented for each new revision.
created:
type: number
description: |
Timestamp representing when the revision was created in milliseconds
since the Unix epoch. Generated by the API if not provided.
type:
type: string
enum:
- edit
- revert
description: |
Programmatically usable string representing the type of this revision.
properties:
type: object
description: |
Properties specific to this revision type.
details:
type: object
default: {}
description: |
Details describing this revision. Intended to be used for
display purposes.
Edit¶
$ref: '#/definitions/revision/revision'
properties:
properties:
edit_type:
type: string
description: |
Programmatically usable string representing the type of edit done in
this revision.
patch:
$ref: 'http://json.schemastore.org/json-patch'
description: |
JSON patch representing the changes made in this revision
Revert¶
$ref: '#/definitions/revision/revision'
properties:
properties:
revision_id:
type: string
description: |
Identifier of the revision to revert to.
Releases¶
Release¶
required:
- revision_id
properties:
id:
type: string
readOnly: true
description: |
The releases's identifier (generated by the API)
url:
type: string
readOnly: true
description: |
API url for accessing the release's description.
number:
type: number
readOnly: true
description: |
The releases's number, starting at `1` for the first release, and
incremented for each new release.
created:
type: number
readOnly: true
description: |
Timestamp representing when the revision was created in milliseconds
since the Unix epoch.
revision_id:
type: string
description: |
Identifier of the revision this release is for.
additionalProperties: false
Permissions¶
required:
- type
properties:
id:
type: string
readOnly: true
description: |
The permission's identifier (generated by the API)
type:
type: string
enum:
- admin
- projects:create
- project:admin
- project:dialogues:read
- project:dialogues:write
- dialogue:read
- dialogue:write
description: |
Identifies the type of this permission.
properties:
type: object
default: {}
description: |
Properties relevant to the permission type.
project:admin
¶
$ref: '#/definitions/permission/permission'
properties:
properties:
type: object
properties:
project_id:
type: string
description: |
Identifier of the project this permission is for.
project:dialogues:read
¶
$ref: '#/definitions/permission/permission'
properties:
properties:
type: object
properties:
project_id:
type: string
description: |
Identifier of the project this permission is for.
project:dialogues:write
¶
$ref: '#/definitions/permission/permission'
properties:
properties:
type: object
properties:
project_id:
type: string
description: |
Identifier of the project this permission is for.
dialogue:read
¶
$ref: '#/definitions/permission/permission'
properties:
properties:
type: object
properties:
project_id:
type: string
description: |
Identifier of the project this permission is for.
dialogue_id:
type: string
description: |
Identifier of the dialogue this permission is for.
dialogue:write
¶
$ref: '#/definitions/permission/permission'
properties:
properties:
type: object
properties:
project_id:
type: string
description: |
Identifier of the project this permission is for.
dialogue_id:
type: string
description: |
Identifier of the dialogue this permission is for.
Channels¶
Channel¶
properties:
id:
type: string
readOnly: true
description: |
The channel's identifier (provided by the API)
url:
type: string
readOnly: true
description: |
API url for accessing the channel description
project_id:
type:
- string
- 'null'
description: |
Identifier for the project currently using this channel. `null` if the
channel is not in use by any projects.
title:
type: string
readOnly: true
description: |
The human-readable title of the channel
type:
type: string
readOnly: true
description: |
Programmatically usable string representing the type of this channel. For
e.g. `sms`, `ussd`.
address:
type: string
readOnly: true
description: |
The address associated with this channel. For example, ``*120*321#``.
is_available:
type: boolean
readOnly: true
description: |
Flag representing whether or not this channel is available for use.
provider:
$ref: '#/definitions/provider/summary'
readOnly: true
description: |
Summary of the provider that associated with this channel.
additionalProperties: false
Channel Summary¶
properties:
id:
type: string
readOnly: true
description: |
The channel's identifier (provided by the API)
url:
type: string
readOnly: true
description: |
API url for accessing the channel description
project_id:
readOnly: true
type:
- string
- 'null'
description: |
Identifier for the project currently using this channel. `null` if the
channel is not in use by any projects.
title:
type: string
readOnly: true
description: |
The human-readable title of the channel
type:
type: string
readOnly: true
description: |
Programmatically usable string representing the type of this channel. For
e.g. `sms`, `ussd`.
address:
type: string
readOnly: true
description: |
The address associated with this channel. For example, ``*120*321#``.
is_available:
type: boolean
readOnly: true
description: |
Flag representing whether or not this channel is available for use.
additionalProperties: false
Providers¶
properties:
id:
type: string
readOnly: true
description: |
The channel's identifier (provided by the API)
url:
type: string
readOnly: true
description: |
API url for accessing the provider description
title:
type: string
readOnly: true
description: |
The human-readable title of the provider
channels:
type: array
readOnly: true
items:
$ref: '#/definitions/channel/summary'
description: |
Summaries of the channels associated with this provider
additionalProperties: false
Provider Summary¶
properties:
id:
type: string
readOnly: true
description: |
The channel's identifier (provided by the API)
url:
type: string
readOnly: true
description: |
API url for accessing the provider description
title:
type: string
readOnly: true
description: |
The human-readable title of the provider
additionalProperties: false