Crumbs REST API
Crumbs is being retired on 31 December 2024. Read the announcement here
|
This document provides public documentation of the Crumbs API.
API Base URL
The API is accessible via:
https://crumbs.newverve.scot/api/1/<resource>
API Tokens
To generate a new API token, go to the API Tokens section in Crumbs (in Jira, select Apps > Crumbs > API Tokens):
These tokens will allow users to authenticate against the Crumbs API.
From this screen users will be able to:
Create new tokens with a label.
View the newly created token (only on generation for security reasons).
Please take note of the token when creating it and keep it safe.
View previously generated tokens by their label.
View when the token was created.
Users can delete/revoke a previously generated token.
Tokens are user specific, and each user can create and see only their API tokens.
Authentication
Use the Authorization HTTP header to submit.
Use Bearer <token>
, and add the token generated in API Tokens screen.
For example with cURL:
curl --request GET 'https://crumbs.newverve.scot/api/1/customer/1' \
--header 'Authorization: Bearer 1c831a91-3559-475e-b4d4-39efd65b9d94'
Authorization
All API resources are authorised against Jira users who have generated any Crumbs tokens, following general Crumbs permissions:
Crumbs Administrator
Crumbs Manager
Crumbs User
Please check Crumbs documentation to find out more about Crumbs permissions, and check Jira permissions (or contact your Jira administrator) to verify the Crumbs permissions of your user.
Please check the resources section in this document to find specific permissions needed for each resource.
API Resources
Resources currently available:
Customer /customer
Represents customers created in Crumbs and in JSM (only JSM Organizations with Crumbs fields saved against them will show up).
Resource Description | Request Details | Response Details |
---|---|---|
Get Customers
Returns a list of Crumbs customers. Only returns JSM organizations with data added in Crumbs. Permissions required, any of the following:
| Query parameters:
Input or request example:
cURL: curl \
--request GET 'https://crumbs.newverve.scot/api/1/customer?startAt=0&fields=address,mainContact,name,eb7e4568-d283-4329-8805-d3b4c4983f1d' \
--header 'Authorization: Bearer 1c831a91-3559-475e-b4d4-39efd65b9d94'
| 200 - Array<Customer> Output or response example:
[
{
"id": "customerId-1",
"fields": {
"name": "Customer A",
"website": "http://www.example.com",
"description": "An example customer",
"address": "1 Example Street",
"region": "Example region",
"zipCode": "A12 3BC",
"city": "A City",
"country": "A Country",
"mainContact": "accountId-1",
"eb7e4568-d283-4329-8805-d3b4c4983f1d": [
{
"id": "abb7bab8-5cbe-4642-b728-90107029b4d4",
"value": "Option 1"
}
]
}
},
{...},
] 401 Returned if the authentication credentials are incorrect or missing. 403 Returned if the user does not have the necessary Crumbs permission. Returned if the user instance is not licensed. |
Get Customer
Returns the queried customer details. Permissions required, any of the following:
| Path parameters:
Input or request example:
cURL: | 200 - Customer Output or response example: 401 Returned if the authentication credentials are incorrect or missing. 403 Returned if the user does not have the necessary Crumbs permission. Returned if the user instance is not licensed. 404 Returned if the customer is not found. |
Create Customer
Creates a new Crumbs customer Permissions required, only:
| Body - Field Values Input or request example: cURL: | 201 - Customer Output or response example: 400 Returned if the request:
401 Returned if the authentication credentials are incorrect or missing. 403 Returned if the user does not have the necessary Crumbs permission. Returned if the user instance is not licensed. |
Update Customer
Updates an existing Crumbs customer Cannot rename JSM organizations due to API limitations. Permissions required, only:
| Path parameters:
Body - Field Values Input or request example: cURL: | 204 Successful request will only return 204 with no other output. 400 Returned if:
401 Returned if the authentication credentials are incorrect or missing. 403 Returned if the user does not have the necessary Crumbs permission. Returned if the user instance is not licensed. 404 Returned if the customer is not found. |
Delete Customer
Deletes a specific Crumbs customer Permissions required, only:
| Path parameters:
Input or request example: cURL: | 204 Successful request will only return 204 with no other output. 401 Returned if the authentication credentials are incorrect or missing. 403 Returned if the user does not have the necessary Crumbs permission. Returned if the user instance is not licensed. 404 Returned if the customer is not found. |
Field /field
The definition of all fields.
Description | Request Details | Response Details |
---|---|---|
Get Fields
Get all fields. Permissions required, any of the following:
| Input or request example: cURL: | 200 - Array<Field> Output or response example: 401 Returned if the authentication credentials are incorrect or missing. 403 Returned if the user does not have the necessary Crumbs permission. Returned if the user instance is not licensed. |
Get Field
Get field. Permissions required, any of the following:
| Path parameters:
Input or request example:
cURL: | 200 - Field Output or response example: 400 Returned if input incorrect format. 401 Returned if the authentication credentials are incorrect or missing. 403 Returned if the user does not have the necessary Crumbs permission. Returned if the user instance is not licensed. 404 Returned if the field cannot be found. |
Issue Link /issueLink
View, link and unlink customers to issues.
Description | Request Details | Response Details |
---|---|---|
Get Issue Links
Get customers linked to an issue. Permissions required, only:
| Path parameters:
Input or request example:
cURL: | 200 - Issue Links Output or response example: 400 Returned if input incorrect format. 401 Returned if the authentication credentials are incorrect or missing. 403 Returned if the user does not have the necessary Crumbs permission. Returned if the user instance is not licensed. 404 Returned if the issue is not found. Returned if the user does not have permission to browse the issue. |
Create issue Link
Link a customer to an issue. Permissions required, only:
| Path parameters:
Body - Issue Link cURL: | 201 Successful request will only return 201 with no other output. 400 Returned if input incorrect format. 401 Returned if the authentication credentials are incorrect or missing. 403 Returned if the user does not have the necessary Crumbs permission. Returned if the user instance is not licensed. 404 Returned if the issue or customer is not found. Returned if the user does not have permission to browse the issue. |
Delete Issue Link
Unlink a customer from an issue. Permissions required, only:
| Path parameter:
Body - Issue Link cURL: | 204 Successful request will only return 204 with no other output. 400 Returned if input incorrect format. 401 Returned if the authentication credentials are incorrect or missing. 403 Returned if the user does not have the necessary Crumbs permission. Returned if the user instance is not licensed. 404 Returned if the issue or customer is not found. Returned if the user does not have permission to browse the issue. |
Note /note
View, edit, delete notes.
Description | Request Details | Response Details |
---|---|---|
Get Notes
Get all notes for a customer. Permissions required, any of the following:
| Query parameters:
Input or request example:
cURL: | 200 - Array<Note> Output or response example (e.g. 2 notes returned): 401 Returned if the authentication credentials are incorrect or missing. 403 Returned if the user does not have the necessary Crumbs permission. Returned if the user instance is not licensed. |
Create Note
Create a note. Permissions required, any of the following:
| Body:
cURL: | 200 - Note Output or response example: 400 Returned if:
401 Returned if the authentication credentials are incorrect or missing. 403 Returned if the user does not have the necessary Crumbs permission. Returned if the user instance is not licensed. 404 Returned if the customer is not found. |
Update Note
Update a note. Permissions required, any of the following:
| Path parameters:
Body:
Input or request example:
cURL: | 200 - Note Output or response example: 401 Returned if the authentication credentials are incorrect or missing. 403 Returned if the user does not have the necessary Crumbs permission. Returned if the user instance is not licensed. 404 Returned if the note is not found. |
Delete Note
Delete a note. Permissions required, any of the following:
| Path parameters:
Input or request example:
cURL: | 200 Successful request will only return 200 with no other output. 401 Returned if the authentication credentials are incorrect or missing. 403 Returned if the user does not have the necessary Crumbs permission. Returned if the user instance is not licensed. 404 Returned if the note is not found. |
Types
All types are described as JSON documents.
Type | Schema | Example |
---|---|---|
Customer | Type: object Properties:
| |
Field Values | Type: object Properties are the Default fields:
Additional properties for each user created field of type Field Value. | |
Field Value | Type: depends on field type
|
|
Field | Type: object Properties:
| |
Field Type | Type: string One of:
| |
Field Configuration | Type: object (properties depends on field type)
| |
Select Field Option | Type: object Properties:
| |
Issue Links | Type: object Properties:
| |
Issue Link | Type: object Property:
| |
Note | Type: object Properties:
|
|