Spaces API Version 2
API Endpoint
https://spaces.databeam.deWelcome to the Spaces API, offering access to the Spaces project service. This document describes version 2 of the API.
Getting Started ¶
Transport ¶
The Spaces API is available via HTTPS only.
SSL 2.0 and SSL 3.0 are disabled.
The base URI for all resources is:
https://{hostname}/spaces/v2
Authorization ¶
All requests require an authorization token in order to function properly. See authentication and authorization for details.
Auth tokens follow the JSON Web Token format. They are to be obtained from the Skalio-ID service. The Spaces service only consumes tokens, but does not issue them.
Rate Limiting ¶
Many resources are protected against misuse or overload caused by badly behaving clients through rate limits according to the Leaky Bucket Algorithm as a Queue concept. Buckets are initially empty. Every request attempts to add a drop to the bucket. If the capacity does not allow this, the request is rejected (see ‘HTTP 509 Rate Limit Exceeded’ in section ‘Error handling’). Buckets drain over time, reducing their specific level and allowing new requests.
HTTP headers inform about the current bucket properties:
-
X-RateLimit-Limit
The total capacity of the current bucket.
Example:
X-RateLimit-Limit: 60 -
X-RateLimit-Remaining
The remaining capacity in the current bucket. Once this value is exhausted, future requests will be rejected until the bucket has been drained sufficiently.
Example:
X-RateLimit-Remaining: 42
Different resources use different buckets:
| Resource | Bucket Identifier | Capacity | Drainrate [1/s] |
|---|---|---|---|
| Login | Email-address of user | 3 | 1/15 |
| Get Onetime Key | User-ID | 10 | 1/30 |
| Environment | no limit | n/a | n/a |
| Other resources | session ID | 60 | 1 |
API Deprecation ¶
Over time, the backend may change and a new version of the API will be released. To inform developers and clients of upcoming changes, the server indicates API deprecation by sending a Warning header with warning-code 229.
Example:
Warning: 299 - “API Deprecation Warning: Support for this request will be dropped soon, please update your client.”
While API deprecation is indicated, the API call will still function as documented. At a later stage, support for individual API calls up to the complete API-path may be dropped. This is indicated by responding with HTTP status code 410 (see section ‘Error handling’).
Payload format ¶
Unless explicitely stated, request and response bodies are encoded in JSON format. Appropriate headers (Content-Type: application/json, Accept: application/json) must be set.
Timestamps are encoded in ISO 8601 format, including timezone offset from UTC. Example:
{ “validDate”: “2037-12-31T15:29:59+00:00” }
Error handling ¶
The API responds with different HTTP Status Codes and messages:
-
HTTP 400 Bad Request
The request cannot be processed for syntax reasons. This could be because of a missing field, an incorrect type or an invalid value. The error message might provide more information. Check your code against the documentation. Retrying the request will not improve your chances of success.
Example:
{ "error": { "code": 400001, "message": "The request cannot be fulfilled.", "details": ["Invalid or unsupported value.", "Please consult the documentation."] } } -
HTTP 401 Not Authorized
Your request is missing an authenticated session ID, your session ID has expired, or your user is not valid. Obtain a new session and/or authenticate it (see the AuthResource).
-
HTTP 403 Forbidden
Your request was syntactically correct, but violated somehing else. Possible reasons are feature- and/or contract-limitations, accessing someone else’s data without authorization. Retrying the request will lead to the same result. The details of the message will provide more details.
Example:
{ "error": { "code": 403001, "message": "This request is forbidden.", "details": ["TTL is not acceptable"] } } -
HTTP 404 Not Found
The request could not be fulfilled, since the resource or entity at the URI does not exist (anymore). Retrying is futile.
-
HTTP 405 Method Not Allowed
The resource or entity does not support the HTTP method. Please consult the documentation.
-
HTTP 406 Not Acceptable
The backend cannot supply the response in the requested mediatype (as per the
Acceptrequest header). Please consult the documentation. You can retry your request, specifying appropriate headers. -
HTTP 409 Conflict
The request was not successful, because the a persistence-opertion failed. This can be temporary, or because another operation has modified the data in the meantime. Reread your data again, apply your changes and retry the request. You haven’t broken anything yet.
-
HTTP 410 Gone
The request was once valid but is no longer acceptable. This is a permanent situation. It indicates that parts of the API have since been deprecated and support for them has been dropped. It is recommended to consult the documentation and update clients.
-
HTTP 413 Request Entity Too Large
The backend is unwilling or unable to process a request body of this size.
-
HTTP 415 Unsupported Mediatype
The backend does not support the request payload, as announced in the
Content-Typeheader. -
HTTP 416 Range Not Satisfiable
This occurs when an upload or download request does not provide acceptable values for headers
RangeorContent-Range. -
HTTP 500 Server Error
Oops! It looks like something went horribly wrong in the backend. You might want to get in touch with us.
-
HTTP 503 Maintenance
The host you’re addressing is currently undergoing maintenance and is not serving requests. You can retry your request until is being accepted again.
-
HTTP 509 Rate Limit Exceeded
The request was not accepted because of a rate limit violation. The API is protected against overload and bruteforce attacks with rate limits. See the section on rate limiting for details. The response contains a
Retry-Afterheader (in seconds) to assist in retrying the request again.Example:
Retry-After: 23
Capacity Management ¶
Capacity ¶
All requests to the root-resource require a valid ID token.
GET https://spaces.databeam.de/spaces/v2/capacity
Requests
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklResponses
Headers
Content-Type: application/jsonBody
{
"capacities": [
{
"orgUid": "z6gm4auyymmwirqx",
"allocatedStorage": 5000000000,
"usedStorage": 84295010
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"capacities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"orgUid": {
"type": "string",
"enum": [
"z6gm4auyymmwirqx"
],
"description": "The unique identifier of the organization."
},
"allocatedStorage": {
"type": "number",
"enum": [
5000000000
],
"description": "The total allocated storage to this organization, in Bytes."
},
"usedStorage": {
"type": "number",
"enum": [
84295010
],
"description": "The currently used storage volume of this organization, in Bytes."
}
},
"required": [
"orgUid",
"allocatedStorage",
"usedStorage"
],
"additionalProperties": false
}
}
},
"required": [
"capacities"
]
}List allGET/spaces/v2/capacity
Returns the capacity details of all organizations the principal has access to.
GET https://spaces.databeam.de/spaces/v2/capacity/WyJV4cNwpGsvjGp4
Requests
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklResponses
Headers
Content-Type: application/jsonBody
{
"orgUid": "z6gm4auyymmwirqx",
"allocatedStorage": 5000000000,
"usedStorage": 84295010
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"orgUid": {
"type": "string",
"description": "The unique identifier of the organization."
},
"allocatedStorage": {
"type": "number",
"description": "The total allocated storage to this organization, in Bytes."
},
"usedStorage": {
"type": "number",
"description": "The currently used storage volume of this organization, in Bytes."
}
},
"required": [
"orgUid",
"allocatedStorage",
"usedStorage"
]
}Exception thrown, if the person does not have the appropriate privileges on the organization.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Exception thrown, if the organization is not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Details of an organizationGET/spaces/v2/capacity/{orgUid}
Fetches the capacity details of the organization. Read-privilege is required.
URI Parameters
- orgUid
string(required) Example: WyJV4cNwpGsvjGp4The UID of the organization.
Space Management ¶
Root ¶
All requests to the root-resource require a valid ID token.
GET https://spaces.databeam.de/spaces/v2
Requests
Headers
Content-Type: application/jsonResponses
Headers
Content-Type: application/jsonBody
{
"spaces": [
{
"name": "Customer project XYZ",
"description": "Hello, world!",
"secure": true,
"orgUid": "rt9oj8ku0cw6r1a.",
"uid": "WyJV4cNwpGsvjGp4",
"sequence": 21732,
"privilege": "read",
"pending": false,
"expiresAt": "null"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"spaces": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"enum": [
"Customer project XYZ"
],
"description": "Visible name of the space, 250 characters max."
},
"description": {
"type": [
"string",
"null"
],
"enum": [
"",
null
],
"description": "optional description of the space"
},
"secure": {
"type": "boolean",
"enum": [
false
],
"description": "Marks the space as secure"
},
"orgUid": {
"type": "string",
"enum": [
"rt9oj8ku0cw6r1a."
],
"description": "ID of the organization the space belongs to. Immutable."
},
"uid": {
"type": "string",
"enum": [
"WyJV4cNwpGsvjGp4"
],
"description": "ID of the space. Readonly, set by the server."
},
"sequence": {
"type": "number",
"enum": [
21732
],
"description": "The sequence number of changes to the space. Strictly monotonic increasing"
},
"privilege": {
"type": "string",
"enum": [
"read",
"write",
"admin"
]
},
"pending": {
"type": "boolean",
"enum": [
false
],
"description": "If true, the collaborator has not yet agreed to the space assignment."
},
"expiresAt": {
"type": [
"string",
"null"
],
"enum": [
"null",
null
],
"description": "ISO 8601 timestamp, when a pending space is removed from the persons list. Null for not-pending spaces."
}
},
"required": [
"name",
"description",
"orgUid",
"uid",
"sequence",
"privilege",
"pending",
"expiresAt"
],
"additionalProperties": false
}
}
},
"required": [
"spaces"
]
}List available spacesGET/spaces/v2
Returns a list of spaces that the authenticated person has access to. List may be empty.
This may include pending space collaborator assignments.
POST https://spaces.databeam.de/spaces/v2
Requests
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklBody
{
"name": "Customer project XYZ",
"description": "Hello, world!",
"secure": true,
"orgUid": "rt9oj8ku0cw6r1a."
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Visible name of the space, 250 characters max."
},
"description": {
"type": [
"string",
"null"
],
"description": "optional description of the space"
},
"secure": {
"type": "boolean",
"description": "Marks the space as secure"
},
"orgUid": {
"type": "string",
"description": "ID of the organization the space belongs to. Immutable."
}
},
"required": [
"name",
"orgUid"
]
}Responses
Headers
Content-Type: application/json
Location: /spaces/v2/{spaceUid}Body
{
"name": "Customer project XYZ",
"description": "Hello, world!",
"secure": true,
"orgUid": "rt9oj8ku0cw6r1a.",
"uid": "WyJV4cNwpGsvjGp4",
"sequence": 21732,
"privilege": "read",
"pending": false,
"expiresAt": "null"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Visible name of the space, 250 characters max."
},
"description": {
"type": [
"string",
"null"
],
"description": "optional description of the space"
},
"secure": {
"type": "boolean",
"description": "Marks the space as secure"
},
"orgUid": {
"type": "string",
"description": "ID of the organization the space belongs to. Immutable."
},
"uid": {
"type": "string",
"description": "ID of the space. Readonly, set by the server."
},
"sequence": {
"type": "number",
"description": "The sequence number of changes to the space. Strictly monotonic increasing"
},
"privilege": {
"type": "string",
"enum": [
"read",
"write",
"admin"
]
},
"pending": {
"type": "boolean",
"description": "If true, the collaborator has not yet agreed to the space assignment."
},
"expiresAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp, when a pending space is removed from the persons list. Null for not-pending spaces."
}
},
"required": [
"name",
"orgUid",
"uid",
"privilege",
"pending"
]
}The space name is missing or longer than 250 characters or the organization UID is missing.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The person does not have the appropriate privileges on the organization.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Create new spacePOST/spaces/v2
Creates a new space and attaches it to the given organization. If the organization does not yet exist, it is automatically created. The originator of this request automatically becomes a collaborator with admin privileges.
Since a space consumes resources of an organization, the principal must have the correct privileges. A space cannot be moved between organizations.
Creating a secure space requires that the principal provides an ID token with authLevel > 1.
POST https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/access?cookie=false
Requests
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklResponses
Headers
Content-Type: application/json
SetCookie: acct=abcdef.123456.ghijkl;Version=1;Comment="Access token";Domain=spaces.skalio.net;Path=/spaces/v2/WyJV4cNwpGsvjGp4;Max-Age=600;Secure;HttpOnlyBody
{
"token": "abcdef.123456.ghijkl"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "The Base64 encoded and signed JWT"
}
},
"required": [
"token"
]
}The person does not have the appropriate privileges on the space.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The space is not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Get access to a spacePOST/spaces/v2/{spaceUid}/access?cookie={cookie}
Requests a new access token for the given space.
Pending collaborators accept their assignment with this API call.
Accessing a secure space requires that the principal provides an ID token with authLevel > 1.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
- cookie
boolean(optional) Example: falseIf true, the access token will be issued as a cookie as well.
Space details ¶
All requests to resources in this group require a valid access token for the space.
GET https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4
Requests
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklResponses
Headers
Content-Type: application/jsonBody
{
"name": "Customer project XYZ",
"description": "Hello, world!",
"secure": true,
"orgUid": "rt9oj8ku0cw6r1a.",
"uid": "WyJV4cNwpGsvjGp4",
"sequence": 21732,
"usedVolume": 84295010,
"usedVolumeCorrectAt": "2019-11-21T17:12:38.251Z",
"collaborators": [
{
"privilege": "read",
"orgReference": "Hello, world!",
"adminReference": "Hello, world!",
"personUid": "mgxrx39qi0p47txk",
"createdAt": "2019-12-02T14:02:33.694Z",
"createdFrom": "bob@example.test",
"pending": false,
"expiresAt": "2019-11-21T17:12:38.251Z"
}
],
"invitations": [
{
"privilege": "read",
"adminReference": "Hello, world!",
"personalNote": "Hello, world!",
"notificationAddress": "alice@example.net",
"uid": "z6gm4auyymmwirqx",
"issuedAt": "2019-12-02T14:02:33.694Z",
"expiresAt": "2019-12-02T28:02:33.694Z",
"publicUrl": "https://spaces.skalio.net/invitation/z6gm4auyymmwirqx",
"inviterUid": "yrm2s1huys4ew12z"
}
],
"files": [
{
"path": "/Desktop/image-33b6e390.jpg",
"intendedSize": 195284,
"createdAt": "2019-11-21T17:12:38.251Z",
"accessedAt": "2019-12-04T09:44:51.014Z",
"modifiedAt": "2019-12-02T14:02:33.694Z",
"mimeType": "image/jpeg",
"uid": "7aj2my8zaxdu9_va",
"size": 195284,
"deletedAt": "null",
"etag": "abc123def456",
"blurHash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
"aspectRatio": 3.141593
}
],
"trash": [
{
"path": "/Desktop/image-33b6e390.jpg",
"intendedSize": 195284,
"createdAt": "2019-11-21T17:12:38.251Z",
"accessedAt": "2019-12-04T09:44:51.014Z",
"modifiedAt": "2019-12-02T14:02:33.694Z",
"mimeType": "image/jpeg",
"uid": "7aj2my8zaxdu9_va",
"size": 195284,
"deletedAt": "null",
"etag": "abc123def456",
"blurHash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
"aspectRatio": 3.141593
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Visible name of the space, 250 characters max."
},
"description": {
"type": [
"string",
"null"
],
"description": "optional description of the space"
},
"secure": {
"type": "boolean",
"description": "Marks the space as secure"
},
"orgUid": {
"type": "string",
"description": "ID of the organization the space belongs to. Immutable."
},
"uid": {
"type": "string",
"description": "ID of the space. Readonly, set by the server."
},
"sequence": {
"type": "number",
"description": "The sequence number of changes to the space. Strictly monotonic increasing"
},
"usedVolume": {
"type": "number",
"description": "Used storage volume of this space, in Bytes."
},
"usedVolumeCorrectAt": {
"type": "string",
"description": "ISO 8601 timestamp when the usedVolume was calculated last."
},
"collaborators": {
"type": "array",
"items": {
"type": "object",
"properties": {
"privilege": {
"type": "string",
"enum": [
"read",
"write",
"admin"
],
"description": "The privilege the person has on the space."
},
"orgReference": {
"type": [
"string",
"null"
],
"enum": [
"",
null
],
"description": "Optional explanatory remarks about the collaborator, visible only to organization administrators."
},
"adminReference": {
"type": [
"string",
"null"
],
"enum": [
"",
null
],
"description": "Optional explanatory remarks about the collaborator, visible only to space administrators."
},
"personUid": {
"type": "string",
"enum": [
"mgxrx39qi0p47txk"
],
"description": "The unique ID of the person."
},
"createdAt": {
"type": [
"string",
"null"
],
"enum": [
"2019-12-02T14:02:33.694Z",
null
],
"description": "Readonly ISO 8601 timestamp of when the collaborator was created."
},
"createdFrom": {
"type": [
"string",
"null"
],
"enum": [
"bob@example.test",
null
],
"description": "Readonly field, reflecting the notification address if the collaborator was created from an invitation."
},
"pending": {
"type": "boolean",
"enum": [
false
],
"description": "Readonly. If true, the person has not yet agreed do the collaborator assignment."
},
"expiresAt": {
"type": [
"string",
"null"
],
"enum": [
"2019-11-21T17:12:38.251Z",
null
],
"description": "ISO 8601 timestamp, when a pending collaborator is removed. Null for not-pending collaborators."
}
},
"required": [
"privilege",
"orgReference",
"adminReference",
"personUid",
"createdAt",
"createdFrom",
"pending",
"expiresAt"
],
"additionalProperties": false
},
"description": "The collaborators with access to the space."
},
"invitations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"privilege": {
"type": "string",
"enum": [
"read",
"write",
"admin"
],
"description": "The desired privilege of the new collaborator."
},
"adminReference": {
"type": [
"string",
"null"
],
"enum": [
"",
null
],
"description": "Optional explanatory remarks about the invitation, visible only to space administrators."
},
"personalNote": {
"type": [
"string",
"null"
],
"enum": [
"",
null
],
"description": "Optional personal note to the invitee."
},
"notificationAddress": {
"type": [
"string",
"null"
],
"enum": [
"alice@example.net",
null
],
"description": "Optional email address of the invitee. If not null, an email notification will be sent."
},
"uid": {
"type": "string",
"enum": [
"z6gm4auyymmwirqx"
],
"description": "The unique identifier of the invitation, also used as the shared secret. Must be presented by the invitee to accept it."
},
"issuedAt": {
"type": "string",
"enum": [
"2019-12-02T14:02:33.694Z"
],
"description": "Readonly ISO 8601 timestamp of when the invitation was issued."
},
"expiresAt": {
"type": "string",
"enum": [
"2019-12-02T28:02:33.694Z"
],
"description": "Readonly ISO 8601 timestamp of when the invitation expires."
},
"publicUrl": {
"type": "string",
"enum": [
"https://spaces.skalio.net/invitation/z6gm4auyymmwirqx"
],
"description": "The public URL of the invitation."
},
"inviterUid": {
"type": "string",
"enum": [
"yrm2s1huys4ew12z"
],
"description": "The unique identifier of the person who issued the invitation."
}
},
"required": [
"privilege",
"adminReference",
"personalNote",
"notificationAddress",
"uid",
"issuedAt",
"expiresAt",
"publicUrl",
"inviterUid"
],
"additionalProperties": false
},
"description": "The list of invitations."
},
"files": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"enum": [
"/Desktop/image-33b6e390.jpg"
],
"description": "A canonical path, absolute from the root of the space."
},
"intendedSize": {
"type": [
"number",
"null"
],
"enum": [
195284,
null
],
"description": "Intended size of the object, set by uploader. Can be used to determine the upload-status."
},
"createdAt": {
"type": [
"string",
"null"
],
"enum": [
"2019-11-21T17:12:38.251Z",
null
],
"description": "ISO 8601 timestamp of file creation time."
},
"accessedAt": {
"type": [
"string",
"null"
],
"enum": [
"2019-12-04T09:44:51.014Z",
null
],
"description": "ISO 8601 timestamp of last file access time."
},
"modifiedAt": {
"type": [
"string",
"null"
],
"enum": [
"2019-12-02T14:02:33.694Z",
null
],
"description": "ISO 8601 timestamp of last file modification time."
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg"
],
"description": "Mimetype of the file. Determined by the server."
},
"uid": {
"type": "string",
"enum": [
"7aj2my8zaxdu9_va"
],
"description": "ID of the file. Readonly, set by the server."
},
"size": {
"type": "number",
"enum": [
195284
],
"description": "Size of the file in bytes. Determined by the server."
},
"deletedAt": {
"type": [
"string",
"null"
],
"enum": [
"null",
null
],
"description": "ISO 8601 timestamp of when the file was moved to trash. Null if not in trash."
},
"etag": {
"type": [
"string",
"null"
],
"enum": [
"abc123def456",
null
],
"description": "Etag value for payload; changes whenever payload is updated."
},
"blurHash": {
"type": [
"string",
"null"
],
"enum": [
"LEHV6nWB2yk8pyo0adR*.7kCMdnj",
null
],
"description": "Encoded blurry placeholder of payload image. Only available if payload can be previewed."
},
"aspectRatio": {
"type": [
"number",
"null"
],
"enum": [
3.141593,
null
],
"description": "Defines the aspect ratio ( width / height ) of a payload image. Only available if the payload can be previewed."
}
},
"required": [
"path",
"intendedSize",
"createdAt",
"accessedAt",
"modifiedAt",
"mimeType",
"uid",
"size",
"deletedAt",
"etag",
"blurHash",
"aspectRatio"
],
"additionalProperties": false
},
"description": "The list of files stored in the space."
},
"trash": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"enum": [
"/Desktop/image-33b6e390.jpg"
],
"description": "A canonical path, absolute from the root of the space."
},
"intendedSize": {
"type": [
"number",
"null"
],
"enum": [
195284,
null
],
"description": "Intended size of the object, set by uploader. Can be used to determine the upload-status."
},
"createdAt": {
"type": [
"string",
"null"
],
"enum": [
"2019-11-21T17:12:38.251Z",
null
],
"description": "ISO 8601 timestamp of file creation time."
},
"accessedAt": {
"type": [
"string",
"null"
],
"enum": [
"2019-12-04T09:44:51.014Z",
null
],
"description": "ISO 8601 timestamp of last file access time."
},
"modifiedAt": {
"type": [
"string",
"null"
],
"enum": [
"2019-12-02T14:02:33.694Z",
null
],
"description": "ISO 8601 timestamp of last file modification time."
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg"
],
"description": "Mimetype of the file. Determined by the server."
},
"uid": {
"type": "string",
"enum": [
"7aj2my8zaxdu9_va"
],
"description": "ID of the file. Readonly, set by the server."
},
"size": {
"type": "number",
"enum": [
195284
],
"description": "Size of the file in bytes. Determined by the server."
},
"deletedAt": {
"type": [
"string",
"null"
],
"enum": [
"null",
null
],
"description": "ISO 8601 timestamp of when the file was moved to trash. Null if not in trash."
},
"etag": {
"type": [
"string",
"null"
],
"enum": [
"abc123def456",
null
],
"description": "Etag value for payload; changes whenever payload is updated."
},
"blurHash": {
"type": [
"string",
"null"
],
"enum": [
"LEHV6nWB2yk8pyo0adR*.7kCMdnj",
null
],
"description": "Encoded blurry placeholder of payload image. Only available if payload can be previewed."
},
"aspectRatio": {
"type": [
"number",
"null"
],
"enum": [
3.141593,
null
],
"description": "Defines the aspect ratio ( width / height ) of a payload image. Only available if the payload can be previewed."
}
},
"required": [
"path",
"intendedSize",
"createdAt",
"accessedAt",
"modifiedAt",
"mimeType",
"uid",
"size",
"deletedAt",
"etag",
"blurHash",
"aspectRatio"
],
"additionalProperties": false
},
"description": "The list of files that have been deleted from the space, but remain in the trash bin."
}
},
"required": [
"name",
"orgUid",
"uid",
"sequence",
"usedVolume",
"usedVolumeCorrectAt",
"collaborators",
"invitations",
"files",
"trash"
]
}The person does not have the appropriate privileges on the space.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The space is not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Get summaryGET/spaces/v2/{spaceUid}
Fetches the details of the space. Read-privilege is required.
This request provides the baseline for synchronisation of the space. It returns a collection of data from the space with the associated sequence value. This value can be used when applying changes via the event stream.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
PUT https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4
Requests
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklBody
{
"name": "Customer project XYZ",
"description": "Hello, world!",
"secure": true
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Visible name of the space, 250 characters max."
},
"description": {
"type": [
"string",
"null"
],
"description": "optional description of the space"
},
"secure": {
"type": "boolean",
"description": "Marks the space as secure"
}
},
"required": [
"name"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"name": "Customer project XYZ",
"description": "Hello, world!",
"secure": true,
"orgUid": "rt9oj8ku0cw6r1a.",
"uid": "WyJV4cNwpGsvjGp4",
"sequence": 21732,
"usedVolume": 84295010,
"usedVolumeCorrectAt": "2019-11-21T17:12:38.251Z",
"collaborators": [
{
"privilege": "read",
"orgReference": "Hello, world!",
"adminReference": "Hello, world!",
"personUid": "mgxrx39qi0p47txk",
"createdAt": "2019-12-02T14:02:33.694Z",
"createdFrom": "bob@example.test",
"pending": false,
"expiresAt": "2019-11-21T17:12:38.251Z"
}
],
"invitations": [
{
"privilege": "read",
"adminReference": "Hello, world!",
"personalNote": "Hello, world!",
"notificationAddress": "alice@example.net",
"uid": "z6gm4auyymmwirqx",
"issuedAt": "2019-12-02T14:02:33.694Z",
"expiresAt": "2019-12-02T28:02:33.694Z",
"publicUrl": "https://spaces.skalio.net/invitation/z6gm4auyymmwirqx",
"inviterUid": "yrm2s1huys4ew12z"
}
],
"files": [
{
"path": "/Desktop/image-33b6e390.jpg",
"intendedSize": 195284,
"createdAt": "2019-11-21T17:12:38.251Z",
"accessedAt": "2019-12-04T09:44:51.014Z",
"modifiedAt": "2019-12-02T14:02:33.694Z",
"mimeType": "image/jpeg",
"uid": "7aj2my8zaxdu9_va",
"size": 195284,
"deletedAt": "null",
"etag": "abc123def456",
"blurHash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
"aspectRatio": 3.141593
}
],
"trash": [
{
"path": "/Desktop/image-33b6e390.jpg",
"intendedSize": 195284,
"createdAt": "2019-11-21T17:12:38.251Z",
"accessedAt": "2019-12-04T09:44:51.014Z",
"modifiedAt": "2019-12-02T14:02:33.694Z",
"mimeType": "image/jpeg",
"uid": "7aj2my8zaxdu9_va",
"size": 195284,
"deletedAt": "null",
"etag": "abc123def456",
"blurHash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
"aspectRatio": 3.141593
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Visible name of the space, 250 characters max."
},
"description": {
"type": [
"string",
"null"
],
"description": "optional description of the space"
},
"secure": {
"type": "boolean",
"description": "Marks the space as secure"
},
"orgUid": {
"type": "string",
"description": "ID of the organization the space belongs to. Immutable."
},
"uid": {
"type": "string",
"description": "ID of the space. Readonly, set by the server."
},
"sequence": {
"type": "number",
"description": "The sequence number of changes to the space. Strictly monotonic increasing"
},
"usedVolume": {
"type": "number",
"description": "Used storage volume of this space, in Bytes."
},
"usedVolumeCorrectAt": {
"type": "string",
"description": "ISO 8601 timestamp when the usedVolume was calculated last."
},
"collaborators": {
"type": "array",
"items": {
"type": "object",
"properties": {
"privilege": {
"type": "string",
"enum": [
"read",
"write",
"admin"
],
"description": "The privilege the person has on the space."
},
"orgReference": {
"type": [
"string",
"null"
],
"enum": [
"",
null
],
"description": "Optional explanatory remarks about the collaborator, visible only to organization administrators."
},
"adminReference": {
"type": [
"string",
"null"
],
"enum": [
"",
null
],
"description": "Optional explanatory remarks about the collaborator, visible only to space administrators."
},
"personUid": {
"type": "string",
"enum": [
"mgxrx39qi0p47txk"
],
"description": "The unique ID of the person."
},
"createdAt": {
"type": [
"string",
"null"
],
"enum": [
"2019-12-02T14:02:33.694Z",
null
],
"description": "Readonly ISO 8601 timestamp of when the collaborator was created."
},
"createdFrom": {
"type": [
"string",
"null"
],
"enum": [
"bob@example.test",
null
],
"description": "Readonly field, reflecting the notification address if the collaborator was created from an invitation."
},
"pending": {
"type": "boolean",
"enum": [
false
],
"description": "Readonly. If true, the person has not yet agreed do the collaborator assignment."
},
"expiresAt": {
"type": [
"string",
"null"
],
"enum": [
"2019-11-21T17:12:38.251Z",
null
],
"description": "ISO 8601 timestamp, when a pending collaborator is removed. Null for not-pending collaborators."
}
},
"required": [
"privilege",
"orgReference",
"adminReference",
"personUid",
"createdAt",
"createdFrom",
"pending",
"expiresAt"
],
"additionalProperties": false
},
"description": "The collaborators with access to the space."
},
"invitations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"privilege": {
"type": "string",
"enum": [
"read",
"write",
"admin"
],
"description": "The desired privilege of the new collaborator."
},
"adminReference": {
"type": [
"string",
"null"
],
"enum": [
"",
null
],
"description": "Optional explanatory remarks about the invitation, visible only to space administrators."
},
"personalNote": {
"type": [
"string",
"null"
],
"enum": [
"",
null
],
"description": "Optional personal note to the invitee."
},
"notificationAddress": {
"type": [
"string",
"null"
],
"enum": [
"alice@example.net",
null
],
"description": "Optional email address of the invitee. If not null, an email notification will be sent."
},
"uid": {
"type": "string",
"enum": [
"z6gm4auyymmwirqx"
],
"description": "The unique identifier of the invitation, also used as the shared secret. Must be presented by the invitee to accept it."
},
"issuedAt": {
"type": "string",
"enum": [
"2019-12-02T14:02:33.694Z"
],
"description": "Readonly ISO 8601 timestamp of when the invitation was issued."
},
"expiresAt": {
"type": "string",
"enum": [
"2019-12-02T28:02:33.694Z"
],
"description": "Readonly ISO 8601 timestamp of when the invitation expires."
},
"publicUrl": {
"type": "string",
"enum": [
"https://spaces.skalio.net/invitation/z6gm4auyymmwirqx"
],
"description": "The public URL of the invitation."
},
"inviterUid": {
"type": "string",
"enum": [
"yrm2s1huys4ew12z"
],
"description": "The unique identifier of the person who issued the invitation."
}
},
"required": [
"privilege",
"adminReference",
"personalNote",
"notificationAddress",
"uid",
"issuedAt",
"expiresAt",
"publicUrl",
"inviterUid"
],
"additionalProperties": false
},
"description": "The list of invitations."
},
"files": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"enum": [
"/Desktop/image-33b6e390.jpg"
],
"description": "A canonical path, absolute from the root of the space."
},
"intendedSize": {
"type": [
"number",
"null"
],
"enum": [
195284,
null
],
"description": "Intended size of the object, set by uploader. Can be used to determine the upload-status."
},
"createdAt": {
"type": [
"string",
"null"
],
"enum": [
"2019-11-21T17:12:38.251Z",
null
],
"description": "ISO 8601 timestamp of file creation time."
},
"accessedAt": {
"type": [
"string",
"null"
],
"enum": [
"2019-12-04T09:44:51.014Z",
null
],
"description": "ISO 8601 timestamp of last file access time."
},
"modifiedAt": {
"type": [
"string",
"null"
],
"enum": [
"2019-12-02T14:02:33.694Z",
null
],
"description": "ISO 8601 timestamp of last file modification time."
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg"
],
"description": "Mimetype of the file. Determined by the server."
},
"uid": {
"type": "string",
"enum": [
"7aj2my8zaxdu9_va"
],
"description": "ID of the file. Readonly, set by the server."
},
"size": {
"type": "number",
"enum": [
195284
],
"description": "Size of the file in bytes. Determined by the server."
},
"deletedAt": {
"type": [
"string",
"null"
],
"enum": [
"null",
null
],
"description": "ISO 8601 timestamp of when the file was moved to trash. Null if not in trash."
},
"etag": {
"type": [
"string",
"null"
],
"enum": [
"abc123def456",
null
],
"description": "Etag value for payload; changes whenever payload is updated."
},
"blurHash": {
"type": [
"string",
"null"
],
"enum": [
"LEHV6nWB2yk8pyo0adR*.7kCMdnj",
null
],
"description": "Encoded blurry placeholder of payload image. Only available if payload can be previewed."
},
"aspectRatio": {
"type": [
"number",
"null"
],
"enum": [
3.141593,
null
],
"description": "Defines the aspect ratio ( width / height ) of a payload image. Only available if the payload can be previewed."
}
},
"required": [
"path",
"intendedSize",
"createdAt",
"accessedAt",
"modifiedAt",
"mimeType",
"uid",
"size",
"deletedAt",
"etag",
"blurHash",
"aspectRatio"
],
"additionalProperties": false
},
"description": "The list of files stored in the space."
},
"trash": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"enum": [
"/Desktop/image-33b6e390.jpg"
],
"description": "A canonical path, absolute from the root of the space."
},
"intendedSize": {
"type": [
"number",
"null"
],
"enum": [
195284,
null
],
"description": "Intended size of the object, set by uploader. Can be used to determine the upload-status."
},
"createdAt": {
"type": [
"string",
"null"
],
"enum": [
"2019-11-21T17:12:38.251Z",
null
],
"description": "ISO 8601 timestamp of file creation time."
},
"accessedAt": {
"type": [
"string",
"null"
],
"enum": [
"2019-12-04T09:44:51.014Z",
null
],
"description": "ISO 8601 timestamp of last file access time."
},
"modifiedAt": {
"type": [
"string",
"null"
],
"enum": [
"2019-12-02T14:02:33.694Z",
null
],
"description": "ISO 8601 timestamp of last file modification time."
},
"mimeType": {
"type": "string",
"enum": [
"image/jpeg"
],
"description": "Mimetype of the file. Determined by the server."
},
"uid": {
"type": "string",
"enum": [
"7aj2my8zaxdu9_va"
],
"description": "ID of the file. Readonly, set by the server."
},
"size": {
"type": "number",
"enum": [
195284
],
"description": "Size of the file in bytes. Determined by the server."
},
"deletedAt": {
"type": [
"string",
"null"
],
"enum": [
"null",
null
],
"description": "ISO 8601 timestamp of when the file was moved to trash. Null if not in trash."
},
"etag": {
"type": [
"string",
"null"
],
"enum": [
"abc123def456",
null
],
"description": "Etag value for payload; changes whenever payload is updated."
},
"blurHash": {
"type": [
"string",
"null"
],
"enum": [
"LEHV6nWB2yk8pyo0adR*.7kCMdnj",
null
],
"description": "Encoded blurry placeholder of payload image. Only available if payload can be previewed."
},
"aspectRatio": {
"type": [
"number",
"null"
],
"enum": [
3.141593,
null
],
"description": "Defines the aspect ratio ( width / height ) of a payload image. Only available if the payload can be previewed."
}
},
"required": [
"path",
"intendedSize",
"createdAt",
"accessedAt",
"modifiedAt",
"mimeType",
"uid",
"size",
"deletedAt",
"etag",
"blurHash",
"aspectRatio"
],
"additionalProperties": false
},
"description": "The list of files that have been deleted from the space, but remain in the trash bin."
}
},
"required": [
"name",
"orgUid",
"uid",
"sequence",
"usedVolume",
"usedVolumeCorrectAt",
"collaborators",
"invitations",
"files",
"trash"
]
}The person does not have the appropriate privileges on the space.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The space is not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Update space detailsPUT/spaces/v2/{spaceUid}
Updates the details of a space. Admin privilege is required.
Changing the secure-flag requires that the principal provides an access token with authLevel > 1.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
DELETE https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4
Requests
Headers
Authorization: Bearer abcdef.123456.ghijklResponses
This response has no content.
The person does not have the appropriate privileges on the organization.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Delete spaceDELETE/spaces/v2/{spaceUid}
Deletes space and all that is attached to it. Space administrator privileges are required to perfom this operation.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
Change events ¶
All requests to resources in this group require a valid access token for the space.
GET https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/events?since=425
Requests
Headers
Authorization: Bearer abcdef.123456.ghijklResponses
Headers
Content-Type: application/jsonBody
{
"events": [
{
"type": "FILE_CREATED",
"sequence": 1462,
"payload": null
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"FILE_CREATED",
"FILE_UPDATED",
"FILE_IN_TRASH",
"FILE_RESTORED",
"FILE_DELETED",
"TRASH_PURGED",
"INVITATION_CREATED",
"INVITATION_CANCELLED",
"INVITATION_ACCEPTED_BY",
"PENDING_COLLABORATOR_CREATED",
"COLLABORATOR_CREATED",
"COLLABORATOR_UPDATED",
"COLLABORATOR_REMOVED",
"SPACE_CREATED",
"SPACE_UPDATED",
"SPACE_AVATAR_UPDATED",
"SPACE_DELETED"
]
},
"sequence": {
"type": "number",
"enum": [
1462
]
},
"payload": {
"type": [
"object",
"null"
],
"properties": {},
"additionalProperties": false,
"description": "variable object, may be null, depends on type"
}
},
"required": [
"type",
"sequence",
"payload"
],
"additionalProperties": false
}
}
},
"required": [
"events"
]
}The person does not have the appropriate privileges on the space. If the person had access privileges before, they have been revoked in the meantime.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The space is not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The requested start sequence as given in since is no longer available.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested range could not be statisfied.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Get recent eventsGET/spaces/v2/{spaceUid}/events?since={since}
Returns the change events for the requested space. The collaborator must have read permissions on the space.
Change events are ordered in a strictly monotonous rising number, called sequence. If optional parameter {since} is provided, the list will contain change events newer than the given sequence. The server stores change events for up to 30 days after which they will be discarded.
When requesting changes, it is recommended the client requests changes starting with his last known sequence. If that cannot be fulfilled anymore, the client has to request the full details of the space.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
- since
number(optional) Example: 425The last known sequence number that the client processed.
Avatar management ¶
An avatar is an image that represents the space.
All requests to resources in this group require a valid access token for the space.
GET https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/avatar?height=240
Requests
Unconditional request
Headers
Authorization: Bearer abcdef.123456.ghijkl
Cookie: acct=abcdef.123456.ghijklResponses
Headers
Content-Type: image/jpeg
Etag: "5180"Body
{... payload ...}Authorization missing
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Read-privileges missing
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Space not found, or it has no avatar.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Conditional GET
Headers
Authorization: Bearer abcdef.123456.ghijkl
If-none-match: "5180"Responses
Headers
Content-Type: image/jpeg
Etag: "5180"Authorization missing
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Read-privileges missing
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Space not found, or it has no avatar.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Get avatarGET/spaces/v2/{spaceUid}/avatar?height={height}
Return the avatar of the space if one has been uploaded. Read-privilege is required to access this resource.
The request must be authenticated with an access token. The token can be provided via
-
the
Authorizationheader (default behaviour), -
as a cookie
Conditional GET requests based on entity tags (Etag) are supported: The server responds with HTTP 304 Not Modified if the client provides a If-none-match header containing the matching entity tag.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
- height
number(optional) Example: 240the requested size of the avatar image
PUT https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/avatar
Requests
Headers
Content-Type: image/jpeg
Authorization: Bearer abcdef.123456.ghijklBody
{... payload ...}Responses
Headers
Content-Type: image/jpegBody
{... payload ...}The image could not be processed, or the payload was too small.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Missing admin privileges to the space.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The space was not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Upload avatarPUT/spaces/v2/{spaceUid}/avatar
Uploads a new avatar, possibly overwriting the previously stored image. Admin-privilege is required to use this resource.
The resource accepts payload with the following content types only:
-
image/jpeg -
image/png -
image/gif -
image/bmp
The avatar must have a size of 1x1 pixels, or size of at least 50x50 pixels.
An uploaded avatar is cropped, resized and re-encoded.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
DELETE https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/avatar
Requests
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklResponses
This response has no content.
Missing admin privileges to the space.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The space was not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Delete avatarDELETE/spaces/v2/{spaceUid}/avatar
Removes the avatar if one has been uploaded. Admin-privilege is required to use this resource.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
Files ¶
Files ¶
Spaces can contain files and directories, which are stored as binary large objects with attached metadata.
Most metadata fields are under the control of the users:
-
pathcontains the fully qualified path and filename of the entity. It must be unique within the space, unless the entity is in trash. -
Timestamps can be used to represent those of the local filesystem:
createdAt,modifiedAtandaccessedAt. For Spaces, theses fields are informational only and are never set by the server. Similarly, no consistency check is being employed.
Other metadata fields are updated only by the Spaces server:
-
sizeandmimeTypeare derived from the actual payload and cannot be changed directly. After uploading data, the payload is scanned to determin the values. -
The
deletedAttimestamp is set by spaces when an object is moved to the trash. Upon trash-recovery, the timestamp is nulled again.
All requests to this resource must be authenticated with a valid access token.
Note: When uploading a file into a directory in Spaces, the directory must exist already.
POST https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/files
Requests
Create the metadata of a file.
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklBody
{
"path": "/Desktop/image-33b6e390.jpg",
"intendedSize": 195284,
"createdAt": "2019-11-21T17:12:38.251Z",
"accessedAt": "2019-12-04T09:44:51.014Z",
"modifiedAt": "2019-12-02T14:02:33.694Z",
"mimeType": "image/jpeg"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "A canonical path, absolute from the root of the space."
},
"intendedSize": {
"type": [
"number",
"null"
],
"description": "Intended size of the object, set by uploader. Can be used to determine the upload-status."
},
"createdAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of file creation time."
},
"accessedAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of last file access time."
},
"modifiedAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of last file modification time."
},
"mimeType": {
"type": "string",
"description": "Mimetype of the file. Determined by the server."
}
},
"required": [
"path",
"mimeType"
]
}Responses
The metadata has been created and an objectId has been assigned.
Headers
Content-Type: application/json
Location: /spaces/v2/WyJV4cNwpGsvjGp4/files/7aj2my8zaxdu9_vaBody
{
"path": "/Desktop/image-33b6e390.jpg",
"intendedSize": 195284,
"createdAt": "2019-11-21T17:12:38.251Z",
"accessedAt": "2019-12-04T09:44:51.014Z",
"modifiedAt": "2019-12-02T14:02:33.694Z",
"mimeType": "image/jpeg",
"uid": "7aj2my8zaxdu9_va",
"size": 195284,
"deletedAt": "null",
"etag": "abc123def456",
"blurHash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
"aspectRatio": 3.141593
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "A canonical path, absolute from the root of the space."
},
"intendedSize": {
"type": [
"number",
"null"
],
"description": "Intended size of the object, set by uploader. Can be used to determine the upload-status."
},
"createdAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of file creation time."
},
"accessedAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of last file access time."
},
"modifiedAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of last file modification time."
},
"mimeType": {
"type": "string",
"description": "Mimetype of the file. Determined by the server."
},
"uid": {
"type": "string",
"description": "ID of the file. Readonly, set by the server."
},
"size": {
"type": "number",
"description": "Size of the file in bytes. Determined by the server."
},
"deletedAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of when the file was moved to trash. Null if not in trash."
},
"etag": {
"type": [
"string",
"null"
],
"description": "Etag value for payload; changes whenever payload is updated."
},
"blurHash": {
"type": [
"string",
"null"
],
"description": "Encoded blurry placeholder of payload image. Only available if payload can be previewed."
},
"aspectRatio": {
"type": [
"number",
"null"
],
"description": "Defines the aspect ratio ( width / height ) of a payload image. Only available if the payload can be previewed."
}
},
"required": [
"path",
"mimeType",
"uid",
"size"
]
}The data could not be parsed or violated a constraint.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Access token missing or not valid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Authorization missing, or path/directory name is not unique, or parent directory is missing.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Space not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Create new file objectPOST/spaces/v2/{spaceUid}/files
Create new file object in the space, without payload. When creating a directory, the directory-specific mime-type inode/directory must be set. Otherwise the mime-type is ignored.
Note: After the successful upload, the connection is held, and the file is merged into the directory structure of files in the space. Only a successful, conflict-free merge will return the request successfully. If conflicts occur, they will be reported to the client. Typical scenario is violation of the unique-filename-per-directory constraint.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
PUT https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/files/7aj2my8zaxdu9_va
Requests
Headers
Authorization: Bearer abcdef.123456.ghijkl
Content-Type: image/pngBody
[... binary payload ...]Responses
The file has been overwritten.
Headers
Content-Type: application/json
Etag: "1847"The file is not found, or is in trash.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The file cannot be written to. Retry later.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Upload payloadPUT/spaces/v2/{spaceUid}/files/{objectId}
Creates or replaces the payload of an existing file, or appends to it. Metadata (with the exception of filesize and mime-type) remains untouched. For the duration of the upload, the object is blocked, disallowing concurrent writes, downloads or modifications of the metadata.
If an upload is interrupted and ends unexpectedly, the partial uploaded data remains persisted. Note that this may include less data than what was sent, depending on internal buffering and when the interruption occured.
Spaces will detect the mime-type of the payload. The Content-Type header is ignored.
NOTE: Only overwrite functionality is available at the moment. Append is not yet implemented.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
- objectId
string(required) Example: 7aj2my8zaxdu9_vaThe ID of the file.
GET https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/files/7aj2my8zaxdu9_va?inline=false
Requests
Request the complete payload.
Headers
Authorization: Bearer abcdef.123456.ghijklResponses
Headers
Content-Type: application/octet-stream
Etag: "1847"
Accept-Ranges: bytes
Content-Disposition: attachment; filename*=utf-8''sales%20figures.xlsx; size=234501Body
[... binary payload ...]Insufficient privileges.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Space or object not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Authorization via cookie
Headers
Cookie: acct=abcdef.123456.ghijklResponses
Headers
Content-Type: application/octet-stream
Etag: "1847"
Accept-Ranges: bytes
Content-Disposition: attachment; filename*=utf-8''sales%20figures.xlsx; size=234501Body
[... binary payload ...]Insufficient privileges.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Space or object not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Conditional GET. Requests payload only if etag has changed.
Headers
Authorization: Bearer abcdef.123456.ghijkl
If-none-match: "1836"Responses
Etag does not match: payload has changed. Sending full payload again (and a new Etag).
Headers
Content-Type: application/octet-stream
Etag: "1847"
Accept-Ranges: bytes
Content-Disposition: attachment; filename*=utf-8''sales%20figures.xlsx; size=234501Body
[... binary payload ...]Etag matches: payload has not changed. Client can deliver locally stored copy of payload.
Headers
Etag: "1836"
Accept-Ranges: bytesInsufficient privileges.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Space or object not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Request only a section of the payload.
Headers
Authorization: Bearer abcdef.123456.ghijkl
Range: bytes=1000-1999Responses
Headers
Content-Type: application/octet-stream
Etag: "1847"
Accept-Ranges: bytes
Content-Range: 1000-1999/284327
Content-Length: 1000
Content-Disposition: attachment; filename*=utf-8''sales%20figures.xlsx; size=234501Body
[... requested range of binary payload ...]Insufficient privileges.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Space or object not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The requested range could not be satisfied.
Headers
Content-Type: application/json
Content-Range: bytes */284327Body
{
"error": {
"code": 0,
"message": "The requested range could not be statisfied.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Download fileGET/spaces/v2/{spaceUid}/files/{objectId}?inline={inline}
Retrieves the uploaded file. To authenticate the request, the access token must be provided in the Authorization header or as a cookie.
Only the payload is streamed to the client. Content-type is set as per the mimetype of the file. Content-length is set based on the requested range or file size respectively. Larger payload is delivered with chunked transfer encoding. Content-disposition headers are set as attachment, unless the query parameter inline is set to true. Filename is UTF8-URL-encoded.
Conditional GET is supported, using the If-none-match request and Etag response headers.
Content-range requests are supported. Clients can specify a single range in the Range header, specifing a bytes-range.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
- objectId
string(required) Example: 7aj2my8zaxdu9_vaThe ID of the file.
- inline
boolean(optional) Example: falseAffects content-disposition response header. If
true, it is set toinline, elseattachment.
HEAD https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/files/7aj2my8zaxdu9_va
Requests
Request the complete payload.
Headers
Authorization: Bearer abcdef.123456.ghijklResponses
Headers
Content-Type: application/octet-stream
Etag: "1847"
Accept-Ranges: bytes
Content-Disposition: attachment; filename*=utf-8''sales%20figures.xlsx; size=234501Insufficient privileges.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Space or object not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Authorization via cookie
Headers
Cookie: acct=abcdef.123456.ghijklResponses
Headers
Content-Type: application/octet-stream
Etag: "1847"
Accept-Ranges: bytes
Content-Disposition: attachment; filename*=utf-8''sales%20figures.xlsx; size=234501Insufficient privileges.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Space or object not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Conditional GET. Requests payload only if etag has changed.
Headers
Authorization: Bearer abcdef.123456.ghijkl
If-none-match: "1836"Responses
Etag does not match: payload has changed. Sending full payload again (and a new Etag).
Headers
Content-Type: application/octet-stream
Etag: "1847"
Accept-Ranges: bytes
Content-Disposition: attachment; filename*=utf-8''sales%20figures.xlsx; size=234501Etag matches: payload has not changed. Client can deliver locally stored copy of payload.
Headers
Etag: "1836"
Accept-Ranges: bytesInsufficient privileges.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Space or object not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Request only a section of the payload.
Headers
Authorization: Bearer abcdef.123456.ghijkl
Range: bytes=1000-1999Responses
Headers
Content-Type: application/octet-stream
Etag: "1847"
Accept-Ranges: bytes
Content-Range: 1000-1999/284327
Content-Length: 1000
Content-Disposition: attachment; filename*=utf-8''sales%20figures.xlsx; size=234501Insufficient privileges.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Space or object not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The requested range could not be satisfied.
Headers
Content-Type: application/json
Content-Range: bytes */284327Body
{
"error": {
"code": 0,
"message": "The requested range could not be statisfied.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Check file existenceHEAD/spaces/v2/{spaceUid}/files/{objectId}
Checks if the file exists. The behaviour is identical to the GET-request with the exception that the payload is never sent. To authenticate the request, the access token must be provided in the Authorization header or as a cookie.
Conditional GET is supported, using the If-none-match request and Etag response headers.
Content-range requests are supported. Clients can specify a single range in the Range header, specifing a bytes-range.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
- objectId
string(required) Example: 7aj2my8zaxdu9_vaThe ID of the file.
GET https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/files/7aj2my8zaxdu9_va/metadata
Requests
Headers
Authorization: Bearer abcdef.123456.ghijklResponses
Headers
Content-Type: application/jsonBody
{
"path": "/Desktop/image-33b6e390.jpg",
"intendedSize": 195284,
"createdAt": "2019-11-21T17:12:38.251Z",
"accessedAt": "2019-12-04T09:44:51.014Z",
"modifiedAt": "2019-12-02T14:02:33.694Z",
"mimeType": "image/jpeg",
"uid": "7aj2my8zaxdu9_va",
"size": 195284,
"deletedAt": "null",
"etag": "abc123def456",
"blurHash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
"aspectRatio": 3.141593
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "A canonical path, absolute from the root of the space."
},
"intendedSize": {
"type": [
"number",
"null"
],
"description": "Intended size of the object, set by uploader. Can be used to determine the upload-status."
},
"createdAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of file creation time."
},
"accessedAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of last file access time."
},
"modifiedAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of last file modification time."
},
"mimeType": {
"type": "string",
"description": "Mimetype of the file. Determined by the server."
},
"uid": {
"type": "string",
"description": "ID of the file. Readonly, set by the server."
},
"size": {
"type": "number",
"description": "Size of the file in bytes. Determined by the server."
},
"deletedAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of when the file was moved to trash. Null if not in trash."
},
"etag": {
"type": [
"string",
"null"
],
"description": "Etag value for payload; changes whenever payload is updated."
},
"blurHash": {
"type": [
"string",
"null"
],
"description": "Encoded blurry placeholder of payload image. Only available if payload can be previewed."
},
"aspectRatio": {
"type": [
"number",
"null"
],
"description": "Defines the aspect ratio ( width / height ) of a payload image. Only available if the payload can be previewed."
}
},
"required": [
"path",
"mimeType",
"uid",
"size"
]
}Insufficient privileges.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Space or object not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Fetch file metadataGET/spaces/v2/{spaceUid}/files/{objectId}/metadata
Retrieves the metadata of an uploaded file. To authenticate the request, the access token must be provided in the Authorization header or as a cookie.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
- objectId
string(required) Example: 7aj2my8zaxdu9_vaThe ID of the file.
PUT https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/files/7aj2my8zaxdu9_va/metadata
Requests
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklBody
{
"path": "/Desktop/image-33b6e390.jpg",
"intendedSize": 195284,
"createdAt": "2019-11-21T17:12:38.251Z",
"accessedAt": "2019-12-04T09:44:51.014Z",
"modifiedAt": "2019-12-02T14:02:33.694Z"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "A canonical path, absolute from the root of the space."
},
"intendedSize": {
"type": [
"number",
"null"
],
"description": "Intended size of the object, set by uploader. Can be used to determine the upload-status."
},
"createdAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of file creation time."
},
"accessedAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of last file access time."
},
"modifiedAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of last file modification time."
}
},
"required": [
"path"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"path": "/Desktop/image-33b6e390.jpg",
"intendedSize": 195284,
"createdAt": "2019-11-21T17:12:38.251Z",
"accessedAt": "2019-12-04T09:44:51.014Z",
"modifiedAt": "2019-12-02T14:02:33.694Z",
"mimeType": "image/jpeg",
"uid": "7aj2my8zaxdu9_va",
"size": 195284,
"deletedAt": "null",
"etag": "abc123def456",
"blurHash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
"aspectRatio": 3.141593
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "A canonical path, absolute from the root of the space."
},
"intendedSize": {
"type": [
"number",
"null"
],
"description": "Intended size of the object, set by uploader. Can be used to determine the upload-status."
},
"createdAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of file creation time."
},
"accessedAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of last file access time."
},
"modifiedAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of last file modification time."
},
"mimeType": {
"type": "string",
"description": "Mimetype of the file. Determined by the server."
},
"uid": {
"type": "string",
"description": "ID of the file. Readonly, set by the server."
},
"size": {
"type": "number",
"description": "Size of the file in bytes. Determined by the server."
},
"deletedAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of when the file was moved to trash. Null if not in trash."
},
"etag": {
"type": [
"string",
"null"
],
"description": "Etag value for payload; changes whenever payload is updated."
},
"blurHash": {
"type": [
"string",
"null"
],
"description": "Encoded blurry placeholder of payload image. Only available if payload can be previewed."
},
"aspectRatio": {
"type": [
"number",
"null"
],
"description": "Defines the aspect ratio ( width / height ) of a payload image. Only available if the payload can be previewed."
}
},
"required": [
"path",
"mimeType",
"uid",
"size"
]
}Insufficient privileges or file/path conflict with other files.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The file is not found, or is in trash.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Update file metadataPUT/spaces/v2/{spaceUid}/files/{objectId}/metadata
Modifies the metadata of the file. Fields that can be modified:
-
intendedSize -
path, including the canonical path of the file within the space -
createdAt -
accessedAt -
modifiedAt
Other fields are ignored.
Before overwriting the payload of an existing object, is it necessary to set the new intendedSize to allow correct triggering of post processing and help detect broken uploads.
The changes are merged into the directory structure of files in the space. Only a successful, conflict-free merge will return the request successfully. If conflicts occur, they will be reported to the client. Typical scenario is violation of the unique-filename-per-directory constraint.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
- objectId
string(required) Example: 7aj2my8zaxdu9_vaThe ID of the file.
GET https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/files/7aj2my8zaxdu9_va/thumbnail-w100.jpg
Requests
Authenticate with access token or cookie.
Headers
Authorization: Bearer abcdef.123456.ghijkl
Cookie: acct=abcdef.123456.ghijklResponses
Headers
Content-Type: image/jpeg
Etag: "1847"
Cache-Control: max-age=60Insufficient privileges.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The file is not found, or is in trash, or a thumbnail could not be rendered for it.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Fetch thumbnailGET/spaces/v2/{spaceUid}/files/{objectId}/thumbnail-w{width}.jpg
Returns a thumbnail of the payload if it exists. The server will try to provide a thumbnail matching the requested size as best as it can, but that is not guaranteed. The request must be authenticated with an access token, either in the Authorization header or as a cookie.
After the payload of a file has been uploaded, thumbnails are generated during post-processing. Previewers will attempt to render the payload into small images. If the payload is not supported, no thumbnail is generated. See Post-processing for details.
It is encouraged that thumbnails are cached by a client. Use conditional GET requests to confirm the validity.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
- objectId
string(required) Example: 7aj2my8zaxdu9_vaThe ID of the file.
- width
number(required) Example: 100The size of the thumbnail.
GET https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/files/7aj2my8zaxdu9_va/preview?width=100&height=100&page=0
Requests
Authenticate with access token.
Headers
Authorization: Bearer abcdef.123456.ghijklResponses
Headers
Content-Type: image/jpegThe submitted query parameters are invalid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Insufficient privileges.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The file is not found, or is in trash, or a preview could not be rendered for it.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The file is being updated.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The mimetype of the requested object is not supported.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Processing of an object mimetype is not supported.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Preview payloadGET/spaces/v2/{spaceUid}/files/{objectId}/preview?width={width}&height={height}&page={page}
Attempts to create a preview of the payload. The image is rendered live, based on the requested dimensions while keeping the aspect ratio, etc. If the payload is not supported, no preview is generated. The request must be authenticated with an access token.
In contrast to thumbnails, the preview is not available while the payload is updated.
While waiting for a preview to be generated, a client can show a blurry placeholder; see BlurHash for details.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
- objectId
string(required) Example: 7aj2my8zaxdu9_vaThe ID of the file.
- width
number(optional) Example: 100The maximum width of the image. Boundaries are 100 < width < 5000. Defaults to 100 if no value is provided.
- height
number(optional) Example: 100The maximum height of the image. Boundaries are 100 < width < 5000. Defaults to 100 if no value is provided.
- page
number(optional) Example: 0The page of a document to be previewed; where applicable. Starts at and defaults to 0. Negative values will be set to 0.
POST https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/files/7aj2my8zaxdu9_va/trash
Requests
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklResponses
This response has no content.
Insufficient privileges.
Body
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"items": {
"type": "string"
},
"description": "English details to error."
}
}
}
},
"$schema": "http://json-schema.org/draft-04/schema#"
}Space or file not found.
Body
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"items": {
"type": "string"
},
"description": "English details to error."
}
}
}
},
"$schema": "http://json-schema.org/draft-04/schema#"
}The file is currently being updated.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Move file to trashPOST/spaces/v2/{spaceUid}/files/{objectId}/trash
Removes a file from the directory-structure of the space and moves it to the trash. While the file is in trash, it cannot be retrieved or overwritten, until it is recovered. write privileges on this space are required to perform the operation.
If the file is a directory, the operation recurses down and applies to all its child-objects.
The Spaces server sets the metadata field deletedAt to the current timestamp.
Note: In the trash, the constraint on uniqueness of the path to files is removed. As a result, it it possible for the trash to contain multiple files with the same path and filename.
The request is idempotent.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
- objectId
string(required) Example: 7aj2my8zaxdu9_vaThe ID of the file.
DELETE https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/files/7aj2my8zaxdu9_va
Requests
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklResponses
This response has no content.
Insufficient privileges, or the file is a not-empty directory.
Body
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"items": {
"type": "string"
},
"description": "English details to error."
}
}
}
},
"$schema": "http://json-schema.org/draft-04/schema#"
}Space not found, or file in trash.
Body
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"items": {
"type": "string"
},
"description": "English details to error."
}
}
}
},
"$schema": "http://json-schema.org/draft-04/schema#"
}The file is currently being updated.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Delete fileDELETE/spaces/v2/{spaceUid}/files/{objectId}
Removes a file from the directory-structure of the space and deletes it, bypassing the trash. This operation is not recoverable. write privileges on this space are required to perform the operation.
Limitations:
-
Only files in the directory-structure of a space can be deleted. Files already in trash must be deleted with a separate request.
-
The delete operation does not recurse to child objects. If the file is a non-empty directory, the delete operation fails.
-
Files cannot be deleted while they are being updated.
The request is idempotent.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
- objectId
string(required) Example: 7aj2my8zaxdu9_vaThe ID of the file.
Trash ¶
When a file is deleted from a space, it does not actually get removed. Instead it is moved to the trash bin area of the space, from where it can be recovered if necessary. However, while files are in the trash, they still consume resources of the space. This resource can be used to permanently delete files that are in the trash already, and free up the resources.
All requests to this resource must be authenticated with a valid access token. write privileges are required to perform these operations.
Delete requests are idempotent.
DELETE https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/trash
Requests
Headers
Authorization: Bearer abcdef.123456.ghijklResponses
This response has no content.
Insufficient privileges.
Body
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"items": {
"type": "string"
},
"description": "English details to error."
}
}
}
},
"$schema": "http://json-schema.org/draft-04/schema#"
}Space not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Empty the trashDELETE/spaces/v2/{spaceUid}/trash
Empties the complete trash. All files currently in trash are permanently deleted.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
DELETE https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/trash/7aj2my8zaxdu9_va
Requests
Headers
Authorization: Bearer abcdef.123456.ghijklResponses
This response has no content.
Insufficient privileges.
Body
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"items": {
"type": "string"
},
"description": "English details to error."
}
}
}
},
"$schema": "http://json-schema.org/draft-04/schema#"
}Space not found, or file is not in trash.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Delete a file from trashDELETE/spaces/v2/{spaceUid}/trash/{objectId}
Permanently deletes the referenced file.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
- objectId
string(required) Example: 7aj2my8zaxdu9_vaThe ID of the file.
POST https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/trash/7aj2my8zaxdu9_va
Requests
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklBody
{
"path": "/Desktop/image-33b6e390.jpg"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "A canonical path, absolute from the root of the space."
}
},
"required": [
"path"
]
}Responses
Headers
Content-Type: application/json
Location: /spaces/v2/WyJV4cNwpGsvjGp4/files/7aj2my8zaxdu9_vaBody
{
"path": "/Desktop/image-33b6e390.jpg",
"intendedSize": 195284,
"createdAt": "2019-11-21T17:12:38.251Z",
"accessedAt": "2019-12-04T09:44:51.014Z",
"modifiedAt": "2019-12-02T14:02:33.694Z",
"mimeType": "image/jpeg",
"uid": "7aj2my8zaxdu9_va",
"size": 195284,
"deletedAt": "null",
"etag": "abc123def456",
"blurHash": "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
"aspectRatio": 3.141593
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "A canonical path, absolute from the root of the space."
},
"intendedSize": {
"type": [
"number",
"null"
],
"description": "Intended size of the object, set by uploader. Can be used to determine the upload-status."
},
"createdAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of file creation time."
},
"accessedAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of last file access time."
},
"modifiedAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of last file modification time."
},
"mimeType": {
"type": "string",
"description": "Mimetype of the file. Determined by the server."
},
"uid": {
"type": "string",
"description": "ID of the file. Readonly, set by the server."
},
"size": {
"type": "number",
"description": "Size of the file in bytes. Determined by the server."
},
"deletedAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of when the file was moved to trash. Null if not in trash."
},
"etag": {
"type": [
"string",
"null"
],
"description": "Etag value for payload; changes whenever payload is updated."
},
"blurHash": {
"type": [
"string",
"null"
],
"description": "Encoded blurry placeholder of payload image. Only available if payload can be previewed."
},
"aspectRatio": {
"type": [
"number",
"null"
],
"description": "Defines the aspect ratio ( width / height ) of a payload image. Only available if the payload can be previewed."
}
},
"required": [
"path",
"mimeType",
"uid",
"size"
]
}Insufficient privileges, or the file cannot be merged into the directory structure.
Body
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"items": {
"type": "string"
},
"description": "English details to error."
}
}
}
},
"$schema": "http://json-schema.org/draft-04/schema#"
}Space or file not found, or file is not in trash.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Recover a file from trashPOST/spaces/v2/{spaceUid}/trash/{objectId}
Recovers a file from trash and restores it to a location in the virtual filesystem. If the request does not specify a target location, the backend will attempt to restore the file to its original location in the directory structure.
Optional request payload:
path, the canonical path of the file within the space
The changes are merged into the directory structure of files in the space. Only a successful, conflict-free merge will return the request successfully. If conflicts occur, they will be reported to the client. Typical scenario is violation of the unique-filename-per-directory constraint or a missing parent directory.
The target directory must already exist.
The metadata field deletedAt is set to null upon successful recovery.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
- objectId
string(required) Example: 7aj2my8zaxdu9_vaThe ID of the file.
Collaborators & Invitations ¶
Collaborators define the privilege a person has on a space. A person can access a space only if there is a corresponding collaborator entry.
Collaborators are created through assignment or invitation. When a collaborator is removed, the person has no access to the space anymore.
A collaborator entry has metadata fields that can be used to manage the relationship better:
-
adminReferenceis a text field that can be set and read by space-administrators only. Collaborators will lesser privileges cannot see or modify the value of this field. -
orgReferenceis a text field that can be set and read by organization-administrators only. Collaborators with lesser privileges cannot see or modify the value of this field.
Note: field orgReference is not yet supported.
Manage collaborators ¶
Collaborators are created through an invitiation process, whereby a space administrator issues an invitation for a person. When the invitee accepts the invitation, he becomes a collaborator on the space.
If the Skalio ID person is known, a space administrator can assign the collaborators directly without going through the invitation process. This assignment creates the new collaborator in a pending state which must be accepted by the person.
Space-administrators can manage existing collaborators.
A person can leave the space they are a collaborator of.
GET https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/collaborators
Requests
Headers
Authorization: Bearer abcdef.123456.ghijklResponses
Headers
Content-Type: application/jsonBody
{
"collaborators": [
{
"privilege": "read",
"orgReference": "Hello, world!",
"adminReference": "Hello, world!",
"personUid": "mgxrx39qi0p47txk",
"createdAt": "2019-12-02T14:02:33.694Z",
"createdFrom": "bob@example.test",
"pending": false,
"expiresAt": "2019-11-21T17:12:38.251Z"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"collaborators": {
"type": "array",
"items": {
"type": "object",
"properties": {
"privilege": {
"type": "string",
"enum": [
"read",
"write",
"admin"
],
"description": "The privilege the person has on the space."
},
"orgReference": {
"type": [
"string",
"null"
],
"enum": [
"",
null
],
"description": "Optional explanatory remarks about the collaborator, visible only to organization administrators."
},
"adminReference": {
"type": [
"string",
"null"
],
"enum": [
"",
null
],
"description": "Optional explanatory remarks about the collaborator, visible only to space administrators."
},
"personUid": {
"type": "string",
"enum": [
"mgxrx39qi0p47txk"
],
"description": "The unique ID of the person."
},
"createdAt": {
"type": [
"string",
"null"
],
"enum": [
"2019-12-02T14:02:33.694Z",
null
],
"description": "Readonly ISO 8601 timestamp of when the collaborator was created."
},
"createdFrom": {
"type": [
"string",
"null"
],
"enum": [
"bob@example.test",
null
],
"description": "Readonly field, reflecting the notification address if the collaborator was created from an invitation."
},
"pending": {
"type": "boolean",
"enum": [
false
],
"description": "Readonly. If true, the person has not yet agreed do the collaborator assignment."
},
"expiresAt": {
"type": [
"string",
"null"
],
"enum": [
"2019-11-21T17:12:38.251Z",
null
],
"description": "ISO 8601 timestamp, when a pending collaborator is removed. Null for not-pending collaborators."
}
},
"required": [
"privilege",
"orgReference",
"adminReference",
"personUid",
"createdAt",
"createdFrom",
"pending",
"expiresAt"
],
"additionalProperties": false
}
}
},
"required": [
"collaborators"
]
}Fetch listGET/spaces/v2/{spaceUid}/collaborators
Fetches a list of all collaborators of this space. Read-privilege is required to perform this request. Includes pending collaborators. For principals with admin-privileges, the adminReference field of a collaborator is populated.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
POST https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/collaborators
Requests
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklBody
{
"privilege": "read",
"orgReference": "Hello, world!",
"adminReference": "Hello, world!",
"personUid": "mgxrx39qi0p47txk",
"personalNote": "Hello, world!"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"privilege": {
"type": "string",
"enum": [
"read",
"write",
"admin"
],
"description": "The privilege the person has on the space."
},
"orgReference": {
"type": [
"string",
"null"
],
"description": "Optional explanatory remarks about the collaborator, visible only to organization administrators."
},
"adminReference": {
"type": [
"string",
"null"
],
"description": "Optional explanatory remarks about the collaborator, visible only to space administrators."
},
"personUid": {
"type": "string",
"description": "The unique ID of the person."
},
"personalNote": {
"type": [
"string",
"null"
],
"description": "Optional personal note to the person."
}
},
"required": [
"privilege",
"personUid"
]
}Responses
Headers
Content-Type: application/json
Location: /spaces/v2/{spaceUid}/collaborators/{uid}Body
{
"privilege": "read",
"orgReference": null,
"adminReference": "Hello, world!",
"personUid": "mgxrx39qi0p47txk",
"createdAt": "2019-12-02T14:02:33.694Z",
"createdFrom": "bob@example.test",
"pending": "true",
"expiresAt": "2019-11-21T17:12:38.251Z"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"privilege": {
"type": "string",
"enum": [
"read",
"write",
"admin"
],
"description": "The privilege the person has on the space."
},
"orgReference": {
"type": [
"string",
"null"
],
"description": "Optional explanatory remarks about the collaborator, visible only to organization administrators."
},
"adminReference": {
"type": [
"string",
"null"
],
"description": "Optional explanatory remarks about the collaborator, visible only to space administrators."
},
"personUid": {
"type": "string",
"description": "The unique ID of the person."
},
"createdAt": {
"type": [
"string",
"null"
],
"description": "Readonly ISO 8601 timestamp of when the collaborator was created."
},
"createdFrom": {
"type": [
"string",
"null"
],
"description": "Readonly field, reflecting the notification address if the collaborator was created from an invitation."
},
"pending": {
"type": "string",
"description": "Readonly. If true, the person has not yet agreed do the collaborator assignment."
},
"expiresAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp, when a pending collaborator is removed. Null for not-pending collaborators."
}
},
"required": [
"privilege",
"personUid",
"pending"
]
}Insufficient privileges.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}A collaborator for this person exists already.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Assign collaboratorPOST/spaces/v2/{spaceUid}/collaborators
Defines a new collaborator, without going through the invitation process. This request requires admin privileges.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
PUT https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/collaborators/mgxrx39qi0p47txk
Requests
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklBody
{
"privilege": "read",
"orgReference": "Hello, world!",
"adminReference": "Hello, world!"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"privilege": {
"type": "string",
"enum": [
"read",
"write",
"admin"
],
"description": "The privilege the person has on the space."
},
"orgReference": {
"type": [
"string",
"null"
],
"description": "Optional explanatory remarks about the collaborator, visible only to organization administrators."
},
"adminReference": {
"type": [
"string",
"null"
],
"description": "Optional explanatory remarks about the collaborator, visible only to space administrators."
}
},
"required": [
"privilege"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"privilege": "read",
"orgReference": "Hello, world!",
"adminReference": "Hello, world!",
"personUid": "mgxrx39qi0p47txk",
"createdAt": "2019-12-02T14:02:33.694Z",
"createdFrom": "bob@example.test",
"pending": false,
"expiresAt": "2019-11-21T17:12:38.251Z"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"privilege": {
"type": "string",
"enum": [
"read",
"write",
"admin"
],
"description": "The privilege the person has on the space."
},
"orgReference": {
"type": [
"string",
"null"
],
"description": "Optional explanatory remarks about the collaborator, visible only to organization administrators."
},
"adminReference": {
"type": [
"string",
"null"
],
"description": "Optional explanatory remarks about the collaborator, visible only to space administrators."
},
"personUid": {
"type": "string",
"description": "The unique ID of the person."
},
"createdAt": {
"type": [
"string",
"null"
],
"description": "Readonly ISO 8601 timestamp of when the collaborator was created."
},
"createdFrom": {
"type": [
"string",
"null"
],
"description": "Readonly field, reflecting the notification address if the collaborator was created from an invitation."
},
"pending": {
"type": "boolean",
"description": "Readonly. If true, the person has not yet agreed do the collaborator assignment."
},
"expiresAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp, when a pending collaborator is removed. Null for not-pending collaborators."
}
},
"required": [
"privilege",
"personUid",
"pending"
]
}Insufficient privileges.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The person is not a collaborator of this space.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Update collaboratorPUT/spaces/v2/{spaceUid}/collaborators/{uid}
Updates the privilege or reference-notes of a collaborator. Admin-privilege is required to perform this request. To update the organization-reference, organization-admin-privileges are required.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
- uid
string(required) Example: mgxrx39qi0p47txkThe ID of the person.
DELETE https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/collaborators/mgxrx39qi0p47txk
Requests
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklResponses
This response has no content.
Insufficient privileges.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Remove collaboratorDELETE/spaces/v2/{spaceUid}/collaborators/{uid}
Removes a collaborator from this space. If the authenticated person removes himself, read-privileges are required. Typically this is intrinsically fulfilled, since being a collaborator grants at least read-privileges.
To remove other collaborators, the admin-privilege is required.
Note: If all collaborators are removed from the space, it can no longer be accessed. Only a person with organization-admin-privileges can then add a collaborator again.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
- uid
string(required) Example: mgxrx39qi0p47txkThe ID of the person.
Manage invitations ¶
Space-administrators can issue invitations to persons, allowing them to become collaborators of a space.
GET https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/invitations
Requests
Headers
Authorization: Bearer abcdef.123456.ghijklResponses
Headers
Content-Type: application/jsonBody
{
"invitations": [
{
"privilege": "read",
"adminReference": "Hello, world!",
"personalNote": "Hello, world!",
"notificationAddress": "alice@example.net",
"uid": "z6gm4auyymmwirqx",
"issuedAt": "2019-12-02T14:02:33.694Z",
"expiresAt": "2019-12-02T28:02:33.694Z",
"publicUrl": "https://spaces.skalio.net/invitation/z6gm4auyymmwirqx",
"inviterUid": "yrm2s1huys4ew12z"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"invitations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"privilege": {
"type": "string",
"enum": [
"read",
"write",
"admin"
],
"description": "The desired privilege of the new collaborator."
},
"adminReference": {
"type": [
"string",
"null"
],
"enum": [
"",
null
],
"description": "Optional explanatory remarks about the invitation, visible only to space administrators."
},
"personalNote": {
"type": [
"string",
"null"
],
"enum": [
"",
null
],
"description": "Optional personal note to the invitee."
},
"notificationAddress": {
"type": [
"string",
"null"
],
"enum": [
"alice@example.net",
null
],
"description": "Optional email address of the invitee. If not null, an email notification will be sent."
},
"uid": {
"type": "string",
"enum": [
"z6gm4auyymmwirqx"
],
"description": "The unique identifier of the invitation, also used as the shared secret. Must be presented by the invitee to accept it."
},
"issuedAt": {
"type": "string",
"enum": [
"2019-12-02T14:02:33.694Z"
],
"description": "Readonly ISO 8601 timestamp of when the invitation was issued."
},
"expiresAt": {
"type": "string",
"enum": [
"2019-12-02T28:02:33.694Z"
],
"description": "Readonly ISO 8601 timestamp of when the invitation expires."
},
"publicUrl": {
"type": "string",
"enum": [
"https://spaces.skalio.net/invitation/z6gm4auyymmwirqx"
],
"description": "The public URL of the invitation."
},
"inviterUid": {
"type": "string",
"enum": [
"yrm2s1huys4ew12z"
],
"description": "The unique identifier of the person who issued the invitation."
}
},
"required": [
"privilege",
"adminReference",
"personalNote",
"notificationAddress",
"uid",
"issuedAt",
"expiresAt",
"publicUrl",
"inviterUid"
],
"additionalProperties": false
}
}
},
"required": [
"invitations"
]
}Fetch listGET/spaces/v2/{spaceUid}/invitations
Fetches a list of pending invitations. Read-privilege is required to perform this request. For principals with admin-privileges, the adminReference field of an invitation is populated.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
POST https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/invitations
Requests
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklBody
{
"privilege": "read",
"adminReference": "Hello, world!",
"personalNote": "Hello, world!",
"notificationAddress": "alice@example.net"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"privilege": {
"type": "string",
"enum": [
"read",
"write",
"admin"
],
"description": "The desired privilege of the new collaborator."
},
"adminReference": {
"type": [
"string",
"null"
],
"description": "Optional explanatory remarks about the invitation, visible only to space administrators."
},
"personalNote": {
"type": [
"string",
"null"
],
"description": "Optional personal note to the invitee."
},
"notificationAddress": {
"type": [
"string",
"null"
],
"description": "Optional email address of the invitee. If not null, an email notification will be sent."
}
},
"required": [
"privilege"
]
}Responses
Headers
Content-Type: application/json
Location: /spaces/v2/{spaceUid}/invitation/{uid}Body
{
"privilege": "read",
"adminReference": "Hello, world!",
"personalNote": "Hello, world!",
"notificationAddress": "alice@example.net",
"uid": "z6gm4auyymmwirqx",
"issuedAt": "2019-12-02T14:02:33.694Z",
"expiresAt": "2019-12-02T28:02:33.694Z",
"publicUrl": "https://spaces.skalio.net/invitation/z6gm4auyymmwirqx",
"inviterUid": "yrm2s1huys4ew12z"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"privilege": {
"type": "string",
"enum": [
"read",
"write",
"admin"
],
"description": "The desired privilege of the new collaborator."
},
"adminReference": {
"type": [
"string",
"null"
],
"description": "Optional explanatory remarks about the invitation, visible only to space administrators."
},
"personalNote": {
"type": [
"string",
"null"
],
"description": "Optional personal note to the invitee."
},
"notificationAddress": {
"type": [
"string",
"null"
],
"description": "Optional email address of the invitee. If not null, an email notification will be sent."
},
"uid": {
"type": "string",
"description": "The unique identifier of the invitation, also used as the shared secret. Must be presented by the invitee to accept it."
},
"issuedAt": {
"type": "string",
"description": "Readonly ISO 8601 timestamp of when the invitation was issued."
},
"expiresAt": {
"type": "string",
"description": "Readonly ISO 8601 timestamp of when the invitation expires."
},
"publicUrl": {
"type": "string",
"description": "The public URL of the invitation."
},
"inviterUid": {
"type": "string",
"description": "The unique identifier of the person who issued the invitation."
}
},
"required": [
"privilege",
"uid",
"issuedAt",
"expiresAt",
"publicUrl",
"inviterUid"
]
}Insufficient privileges.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Create invitationPOST/spaces/v2/{spaceUid}/invitations
Creates a new invitation. If the request body contains an email address, the invitee is notified via email. Admin-privilege is required for this request
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
DELETE https://spaces.databeam.de/spaces/v2/WyJV4cNwpGsvjGp4/invitations/z6gm4auyymmwirqx
Requests
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklResponses
This response has no content.
Insufficient privileges.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Cancel an invitationDELETE/spaces/v2/{spaceUid}/invitations/{uid}
Removes the pending invitation. Renders a previously issued invitation useless. Requires admin-privilege on the space.
URI Parameters
- spaceUid
string(required) Example: WyJV4cNwpGsvjGp4The ID of the space.
- uid
string(required) Example: z6gm4auyymmwirqxThe ID of the invitation.
Interact with invitations ¶
This resource is intended for invitees, to fetch information about an invitation and to accept it.
GET https://spaces.databeam.de/spaces/v2/invitation/z6gm4auyymmwirqx
Requests
Headers
Content-Type: application/jsonResponses
Headers
Content-Type: application/jsonBody
{
"personalNote": "Hello, world!",
"privilege": "read",
"expiresAt": "2019-12-02T28:02:33.694Z",
"inviterUid": "yrm2s1huys4ew12z",
"space": {
"name": "Customer project XYZ",
"description": "Hello, world!",
"secure": true,
"orgUid": "rt9oj8ku0cw6r1a.",
"uid": "WyJV4cNwpGsvjGp4"
},
"uidToken": "abcdef.123456.ghijkl"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"personalNote": {
"type": [
"string",
"null"
],
"description": "Optional personal note to the invitee."
},
"privilege": {
"type": "string",
"enum": [
"read",
"write",
"admin"
],
"description": "The desired privilege of the new collaborator."
},
"expiresAt": {
"type": "string",
"description": "Readonly ISO 8601 timestamp of when the invitation expires."
},
"inviterUid": {
"type": "string",
"description": "The unique identifier of the person who issued the invitation."
},
"space": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Visible name of the space, 250 characters max."
},
"description": {
"type": [
"string",
"null"
],
"description": "optional description of the space"
},
"secure": {
"type": "boolean",
"description": "Marks the space as secure"
},
"orgUid": {
"type": "string",
"description": "ID of the organization the space belongs to. Immutable."
},
"uid": {
"type": "string",
"description": "ID of the space. Readonly, set by the server."
}
},
"required": [
"name",
"orgUid",
"uid"
],
"description": "The space this invitation is about."
},
"uidToken": {
"type": "string",
"description": "A short-lived uidToken that can authorize requesting the public profile of the inviter."
}
},
"required": [
"privilege",
"expiresAt",
"inviterUid",
"space",
"uidToken"
]
}The invitation is not found or has expired already.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Get detailsGET/spaces/v2/invitation/{uid}
Fetches the public details of an invitation. It must still be valid.
This request does not require any space privileges.
The response contains a custom uidToken that can be used to authorize the request for the public profile and avatar of the inviter (identified by inviterUid). This token is short lived, shall not be cached and shall only be used to resolve public information of the inviter. A new token is issued with every response.
URI Parameters
- uid
string(required) Example: z6gm4auyymmwirqxThe ID of the invitation.
GET https://spaces.databeam.de/spaces/v2/invitation/z6gm4auyymmwirqx/avatar?height=240
Requests
Headers
Content-Type: application/jsonResponses
Headers
Content-Type: image/pngBody
[PNG bytes]The invitation is not found or has expired already, or the space has been deleted or it has no avatar.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Get space avatarGET/spaces/v2/invitation/{uid}/avatar?height={height}
Fetches the avatar of the space of an invitation. The invitation must still be valid. The space must not yet been deleted.
This request does not require any space privileges.
URI Parameters
- height
number(optional) Example: 240the requested size of the avatar image
- uid
string(required) Example: z6gm4auyymmwirqxThe ID of the invitation.
POST https://spaces.databeam.de/spaces/v2/invitation/z6gm4auyymmwirqx/accept
Requests
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklResponses
This response has no content.
Authentication required. The person accepting the invitation has not provided an ID token.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The invitation is not found or has expired already.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The person identified by the ID token is already a collaborator.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Accept invitationPOST/spaces/v2/invitation/{uid}/accept
This request completes the invitation process and creates a new collaborator for the space associated with the invitation. It must still be valid, and the person accepting it must not be a collaborator of the space yet.
Obviously, this request does not require any space privileges.
An invitation can be accepted only once. After successful acceptance, it is removed automatically.
URI Parameters
- uid
string(required) Example: z6gm4auyymmwirqxThe ID of the invitation.
Generated by aglio on 10 Apr 2024