1. Reference
2. Web API

Web API

The Weavy 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.

OpenAPI description

The Weavy 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.

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

The latest version of the description is always available here, but you can also navigate to /api/openapi.json in your Weavy environment for a version that matches your deployment.

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 server-to-server and user-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"    
}

Code samples

For most operations the documentation will include one or more example requests using curl.

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

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

Summary representations

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

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

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

Detailed representations

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

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

curl https://{WEAVY-SERVER}/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 top 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 https://{WEAVY-SERVER}/api/users?skip=5&top=5 
-H "Authorization: Bearer {ACCESS-TOKEN | API-KEY}"