1. Reference
2. Web API

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.

The API is based on the following guiding principles:

• Only available over HTTPS.
• Uses Bearer authentication with token in the Authorization header.
• Utilizes standard HTTP methods and status codes.
• Body parameters should be sent with Content-Type: application/json unless stated otherwise.
• Always returns JSON. Empty arrays and properties with null values will be omitted from the response.
• All dates return in UTC time, using the ISO 8601 format YYYY-MM-DDTHH:MM:SSZ.

Authentication

Authentication is done by passing a Bearer token in the Authorization header. For details on how to acquire tokens for different scenarios such as user-to-server and server-to-server see the authentication article.

Authorization: Bearer {ACCESS-TOKEN | API-KEY}

HTTP methods

Where possible, the API strives to use appropriate HTTP methods for actions.

Response codes

Every request will return a status code that indicates the success of the response. The list below details the most common responses and their meaning.

API calls that result in an error code (HTTP 400 or higher) produces a problem detail response.

Example: 404 Not Found

{
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"    
}

Summary representations

When you fetch a list of resources, the response includes a subset of properties for that resource. This is the summary representation of the resource. Some properties are computationally expensive for the API to provide, and for performance reasons, the summary representation excludes those properties. To obtain them, fetch the detailed representation.

Example: When you get a list of users, you get the summary representation of each user.

curl {WEAVY-URL}/api/users
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}" 

Detailed representations

When you fetch an individual resource, the response typically includes all properties for that resource. This is the detailed representation of the resource.

Example: When you fetch an individual user, the response typically includes all properties for that user. This is the detailed representation.

curl {WEAVY-URL}/api/users/bugs-bunny
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}" 

Pagination

Requests that return multiple items is limited to 25 items by default, but you can specify further items (up to 100) with the take parameter. To return a specific range of items you can combine that with the skip parameter.

Example: Return users 6-10 by skipping the first 5 records and then returning the next 5 records.

curl {WEAVY-URL}/api/users?skip=5&take=5 
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}" 

Reference documentation

The API is fully described in an OpenAPI 3.0 compliant document. OpenAPI is a standard specification for describing APIs which enable both humans and machines to easily discover the capabilities of an API. The latest version of the OpenAPI description is always available here, but you can also navigate to /api/openapi.json in your Weavy environment for a description that matches your environment version.

Internally at Weavy we use the OpenAPI description to generate the reference documentation you see here, but it can also be useful when working with third-party tools such as Insomnia and Postman for exploring and interacting with the API.

Code samples

For most operations the reference documentation will include one or more example requests using curl (for more information about curl, skip ahead to the section about using the API below).

curl {WEAVY-URL}/api/files/57/comments
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"

Note that you should replace the {WEAVY-URL} placeholder with the url to your Weavy environment. For requests that require authentication you should also replace the {ACCESS-TOKEN} and/or {API-KEY} placeholders when present.

Using the API

You can interact with the API using any tool capable of making HTTP requests. The section below 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 API key

Go to the environment page on your Weavy account and create an API key (you vill need this when authenticating your requests).

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: {WEAVY-URL}/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-URL} with the url to your Weavy environment and {API-KEY} with your API key.

curl -X GET {WEAVY-URL}/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 {WEAVY-URL}/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 {WEAVY-URL}/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 take 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 {WEAVY-URL}/api/users?take=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 {WEAVY-URL}/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 {WEAVY-URL}/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"
}