SelfGuide (v1)
Download OpenAPI specification:Download
The SelfGuide API is a programmatic interface to interact with SelfGuide from third party applications, automation platforms and scripts. It complements the product user interface and serves two main goals:
- Integrate SelfGuide in third-party applications by utilizing the search endpoint to retrieve relevant instructions and directly open the instruction
- Automate SelfGuide administrative tasks like user provisioning, user management and content channel membership assignments
This document is a reference for the available endpoints. For each endpoint, detailed information is available like required authorization; available methods; required parameters or request bodies; and the response body.
The API is available on a tenant-specific URL of the form
https://demo-api.selfguide.com, where demo should be replaced with your
own SelfGuide tenant name as applicable.
Sign in
Sign in using an existing application identity to retrieve a JWT token for authenticating all other API requests.
For help with creating application keys, please refer to this Instruction.
Request Body schema: application/jsonrequired
Application identity and secret key
| applicationKey required | string <guid> |
| secretKey required | string <password> |
Responses
Request samples
- Payload
{- "applicationKey": "12345678-1234-1234-1234-1234567890ab",
- "secretKey": "1234567890abcdef1234567890abcdef12345678"
}Response samples
- 200
{- "access_token": "2YotnFZFEjr1zCsicMWpAA",
- "token_type": "Bearer",
- "expires_in": 14400
}Get list of the users assigned to a content channel
Gets the list of all users assigned to the content channel with the specified ID. The response includes each user's ID, which can be used to remove a user from the content channel.
Authorizations:
path Parameters
| contentChannelId required | string <guid> Example: 12345678-1234-1234-1234-1234567890ab ID of the content channel to act on |
Responses
Response samples
- 200
[- {
- "id": "12345678-1234-1234-1234-1234567890ab",
- "username": "user@selfguide.com"
}
]Assign a user to the content channel
The specified user will be assigned to the content channel. They may now see content assigned to the same content channel.
Authorizations:
path Parameters
| contentChannelId required | string <guid> Example: 12345678-1234-1234-1234-1234567890ab ID of the content channel to act on |
Request Body schema: application/jsonrequired
Username of the user to assign to the content channel
| username required | string <email> |
Responses
Request samples
- Payload
{- "username": "user@selfguide.com"
}Remove a user from a content channel
The specified user will be removed from the content channel. They will no longer be able to view content assigned to that content channel.
Authorizations:
path Parameters
| contentChannelId required | string <guid> Example: 12345678-1234-1234-1234-1234567890ab ID of the content channel to remove the user from |
| userId required | string <guid> Example: 12345678-1234-1234-1234-1234567890ab ID of the user to remove (NOTE: This is not the username) |
Responses
Create user
Create a new user in SelfGuide
Authorizations:
Request Body schema: application/jsonrequired
User to create. Different request bodies are possible depending on whether your tenant uses AzureAD/Entra to manage logins or not.
| username required | string <email> Username that the user will log in with |
| firstname required | string First name of the user |
| lastname required | string Last name of the user |
| role | string Default: "User" Enum: "User" "Editor" "SelfGuide Manager" "Admin" Role of the user in SelfGuide |
| password | string <password> This field becomes mandatory if |
| canChangePassword | boolean Default: true Whether the user is permitted to change their own password |
| informUser | boolean Default: true Whether the user will receive an email with their login details. If this field is set to |
Responses
Request samples
- Payload
{- "username": "john.doe@selfguide.com",
- "firstname": "John",
- "lastname": "Doe",
- "role": "User",
- "password": "pa$$word",
- "canChangePassword": true,
- "informUser": true
}Update user
Update one or more properties of the user
Authorizations:
path Parameters
| userId required | string <guid> Example: 12345678-1234-1234-1234-1234567890ab ID of the user to delete (NOTE: This is not the username) |
Request Body schema: application/jsonrequired
Update one or more properties of a user. The request body is an array, with an entry for each property to update. Different request bodies are possible depending on whether your tenant uses AzureAD/Entra to manage logins or not.
| op required | string Value: "replace" The operation to be performed on the specified property. Currently only 'replace' is supported. |
| path required | string Enum: "firstname" "lastname" "role" "canChangePassword" The name of the property to update |
required | string or boolean The new value of the property. The type depends on the property to update. |
Responses
Request samples
- Payload
[ ]Get or search for instructions
Get a list of instructions, optionally filtered by some parameters. For each instruction some general data such as its title, description, and step count is returned.
For User role, this endpoint will return instructions that are in the "Organization" content channel, as well as instructions in the "Everyone" content channel if Guest Mode is enabled. It does not return instructions in a custom content channel, nor is it possible to assign an application identity to a custom content channel.
For Guest role, this endpoint will return instructions that are in the "Everyone" content channel if Guest Mode is enabled.
When using the optional filtering parameters they may be freely combined.
Authorizations:
query Parameters
| searchTerm | string Examples:
Optional search query to search the instruction library with |
| tags | Array of strings Examples:
Optional tags to filter the instruction library by. These names must be an exact match. |
| applications | Array of strings Examples:
Optional applications to filter the instruction library by. These names must be an exact match. |
Responses
Response samples
- 200
{- "hitCount": 1,
- "hits": [
- {
- "id": "31e35fe7-4939-47f1-c3be-08db2c4aed98",
- "title": "Title of an instruction",
- "description": "Description of an instruction",
- "applications": [
- "SelfGuide"
], - "tags": [
- "Getting Started"
], - "stepCount": 9
}
]
}