Using the Web API
The Weavy environment exposes a Web API under the /api path with endpoints for manipulating objects such as Apps, Users, Messages, Files etc.
You can interact with the API using any tool capable of making HTTP requests. This article describes how to get started with the Web API using curl.
Install curl
Check if curl is installed on your machine by executing curl --version on the command line.
If the output is information about the version of curl, it is installed, but if you get a message similar to command not found you need to download and install curl.
For more information, see the curl project download page.
Create an API key
Go to the environment page on your Weavy account and create an API key (you vill need this when authenticating your requests).
For more information on authentication and how to acquire tokens for different scenarios such as server-to-server and user-to-server see the Authentication article.
Making a request
To make a request, first find the HTTP method and path for the operation you want to use. For example the List users operation
uses the GET method and the /api/users path.
Prepend the base URL for your environment to the path to get the full URL: https://{WEAVY-SERVER}/api/users.
Use the curl command in your command line to make your request. Specify the the -X flag followed by the HTTP method and full URL.
You also need to specify your API key in the Authorization header with the -H flag.
Replace {WEAVY-SERVER} with the hostname of your Weavy environment and {API-KEY} with your API key.
curl -X GET https://{WEAVY-SERVER}/api/users
-H "Authorization: Bearer {API-KEY}"
Normally you don't need to specify the HTTP method when using curl as the correct method is often inferred by other command line options:
curl https://{WEAVY-SERVER}/api/users
-H "Authorization: Bearer {API-KEY}"
Continue reading to learn how to send parameters, and use the response.
Using path parameters
Path parameters modify the operation path. For example, the Get user path is /api/users/{id}.
The curly brackets {} denote path parameters that you need to specify. In this case, you must specify the user id.
Example: To get the user with id 57, replace {id} with 57.
curl https://{WEAVY-SERVER}/api/users/57
-H "Authorization: Bearer {API-KEY}"
Using query parameters
Query parameters allow you to control what data is returned for a request. For example, a query parameter may let you specify how many items are returned when the response is paginated.
By default, the List users operation returns 25 users, sorted in descending order by the date they were created.
You can use the top parameter to return 5 users instead of 25, and you can use the order_by parameter to sort the users by their display name instead of by the date they were created.
For curl commands, add a ? to the end of the path, then append your query parameter name and value in the form parameter_name=value. Separate multiple query parameters with &.
curl https://{WEAVY-SERVER}/api/users?top=5&order_by=display_name
-H "Authorization: Bearer {API-KEY}"
Using body parameters
Body parameters allow you to pass additional data to the API using Content-Type: application/json.
For example, the Create user operation requires you to specify a uid for the new user. It also lets you specify other information, such as name, email etc.
For curl commands, use the --json flag to send JSON data in a POST request.
curl https://{WEAVY-SERVER}/api/users
-H "Authorization: Bearer {API-KEY}"
--json "{ 'uid': 'jdoe', 'name': 'John Doe' }"
Using the response
Every request will return an HTTP status code that indicates the success of the response. Additionally, the response will include headers that give more details about the response.
To view the status code and headers with curl, use the -i flag when you send your request.
For example, this request:
curl -i https://{WEAVY-SERVER}/api/users/57
-H "Authorization: Bearer {API-KEY}"
returns the following response code and headers:
HTTP/1.1 200 OK
Content-Length: 164
Content-Type: application/json; charset=utf-8
Date: Thu, 10 Aug 2023 12:16:18 GMT
Many operations will also return a response body in JSON format.
For example, the request above returns information about the user with id 57:
{
"id": 57,
"uid": "jdoe",
"display_name": "John Doe",
"created_at": "2023-08-10T12:15:11.8433333Z",
"modified_at": "2023-08-10T12:15:11.8433333Z"
}
Next steps
For more information about the operations that you can use, see the Web API reference documentation.