Docs

Appearance

Open console

Reference

Claims

REST API reference for Claims: configure claims and request the claim of a device. 10 operations.

Reference5 min read

For the base URL, authentication and errors, see the REST API overview.

POST /v1/claims ​

  • Request: POST /v1/claims
  • Operation: RequestClaim
  • Operation ID: Claim_Request
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
codestringyesPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
projectstringyesPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.

Example request: Claim into a project

bash
curl -X POST 'https://YOUR_SERVER/v1/claims' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "a1B2c3D4e5",
  "project": "my_greenhouse"
}'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/claims/{code} ​

  • Request: GET /v1/claims/
  • Operation: ReadClaim
  • Operation ID: Claim_Read
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
codepathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/claims/YOUR_CODE' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/claims ​

  • Request: GET /v1/users/{user}/claims
  • Operation: ListClaims
  • Operation ID: Claim_List
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/claims' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

Response example (200)

json
[
  {
    "claim": "kit_0042",
    "created": 1792263090794,
    "description": "Gateway, sensor and dashboard shipped in box 0042",
    "enabled": true,
    "modified": 1792263090794,
    "name": "Starter kit 0042"
  }
]

POST /v1/users/{user}/claims ​

  • Request: POST /v1/users/{user}/claims
  • Operation: CreateClaim
  • Operation ID: Claim_Create
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes

Request body (application/json, required)

A claim lets another account take some of your resources into one of the projects you share with it: it opens the claim URL (or posts the code to /v1/claims), and the listed resources join that project; 'members' are added to it with 'members_roles' (global roles). 'max_claims' limits how many times the code works (0 = unlimited).

FieldTypeRequiredConstraintsDescription
claimstringyesPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
configobjectyes
config.domainstringnoPattern: ^([a-zA-Z0-9-_]+\.)*[a-zA-Z0-9][a-zA-Z0-9-_]+\.[a-zA-Z]{2,11}?$
config.max_claimsintegernoMinimum: 0
config.membersarray of stringno
config.members_rolesarray of stringno
config.projectsarray of stringno
config.resourcesarray of objectyes
config.resources[].identifiersarray of stringno
config.resources[].typestringno
descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
enabledbooleanyes
namestringyesMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.

Example request: Starter kit

bash
curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/claims' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "claim": "kit_0042",
  "config": {
    "max_claims": 1,
    "members": [
      "support"
    ],
    "members_roles": [
      "viewer"
    ],
    "resources": [
      {
        "identifiers": [
          "kit_0042_gw",
          "kit_0042_sensor"
        ],
        "type": "device"
      },
      {
        "identifiers": [
          "kit_dashboard"
        ],
        "type": "dashboard"
      }
    ]
  },
  "description": "Gateway, sensor and dashboard shipped in box 0042",
  "enabled": true,
  "name": "Starter kit 0042"
}'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/claims/{claim} ​

  • Request: GET /v1/users/{user}/claims/
  • Operation: ReadClaimConfig
  • Operation ID: Claim_ReadConfig
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
claimpathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/claims/YOUR_CLAIM' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

Response example (200, Starter kit)

json
{
  "claim": "kit_0042",
  "config": {
    "max_claims": 1,
    "members": [
      "support"
    ],
    "members_roles": [
      "viewer"
    ],
    "resources": [
      {
        "identifiers": [
          "kit_0042_gw",
          "kit_0042_sensor"
        ],
        "type": "device"
      },
      {
        "identifiers": [
          "kit_dashboard"
        ],
        "type": "dashboard"
      }
    ]
  },
  "created": 1792263090794,
  "description": "Gateway, sensor and dashboard shipped in box 0042",
  "enabled": true,
  "modified": 1792263090794,
  "name": "Starter kit 0042"
}

PUT /v1/users/{user}/claims/{claim} ​

  • Request: PUT /v1/users/{user}/claims/
  • Operation: UpdateClaim
  • Operation ID: Claim_Update
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
claimpathstringyes

Request body (application/json, required)

config replaces the whole claim configuration.

FieldTypeRequiredConstraintsDescription
configobjectno
config.domainstringnoPattern: ^([a-zA-Z0-9-_]+\.)*[a-zA-Z0-9][a-zA-Z0-9-_]+\.[a-zA-Z]{2,11}?$
config.max_claimsintegernoMinimum: 0
config.membersarray of stringno
config.members_rolesarray of stringno
config.projectsarray of stringno
config.resourcesarray of objectyes
config.resources[].identifiersarray of stringno
config.resources[].typestringno
descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
enabledbooleanno
namestringnoMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.

Example request: Disable the code

bash
curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/claims/YOUR_CLAIM' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": false
}'

Example body: Rename

json
{
  "name": "Starter kit 0042 - returned"
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

DELETE /v1/users/{user}/claims/{claim} ​

  • Request: DELETE /v1/users/{user}/claims/
  • Operation: DeleteClaim
  • Operation ID: Claim_Delete
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
claimpathstringyes

Example request

bash
curl -X DELETE 'https://YOUR_SERVER/v1/users/YOUR_USER/claims/YOUR_CLAIM' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

GET /v1/users/{user}/claims/{claim}/clone ​

  • Request: GET /v1/users/{user}/claims/{claim}/clone
  • Operation: CloneClaimConfig
  • Operation ID: Claim_CloneConfig
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
claimpathstringyes

Example request

bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/claims/YOUR_CLAIM/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Responses

StatusDescription
200ok
401unauthorized
403forbidden

POST /v1/users/{user}/claims/{claim}/clone ​

  • Request: POST /v1/users/{user}/claims/{claim}/clone
  • Operation: CloneClaim
  • Operation ID: Claim_Clone
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
claimpathstringyes

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
claimstringyesPattern: ^[a-zA-Z0-9_-]{1,32}$A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters.
descriptionstringnoMaximum length: 255A brief description of the resource, providing context or additional information, limited to 255 characters.
enabledbooleanno
namestringnoMaximum length: 255The name of the resource, limited to 255 characters. It can include any character.

Example request: Copy with a new id

bash
curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/claims/YOUR_CLAIM/clone' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "claim": "copy_of_claim"
}'

Example body: Copy with name and description

json
{
  "claim": "line_2_claim",
  "description": "Same configuration as the original, for production line 2",
  "name": "Line 2 copy"
}

Responses

StatusDescription
200ok
401unauthorized
403forbidden

PUT /v1/users/{user}/claims/{claim}/projects ​

  • Request: PUT /v1/users/{user}/claims/{claim}/projects
  • Operation: UpdateClaimProjects
  • Operation ID: Claim_UpdateProjects
  • Authentication: access token, Authorization: Bearer YOUR_TOKEN

Parameters

NameInTypeRequiredDescription
userpathstringyes
claimpathstringyes

Request body (application/json, required)

FieldTypeRequiredConstraintsDescription
(body)array of stringnoProjects the resource belongs to, as <owner>@<project> ids. Replaces the whole list: read the current one first to add or remove a single project; [] removes it from every project.

Example request: No projects

bash
curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/claims/YOUR_CLAIM/projects' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[]'

Example body: One project

json
[
  "YOUR_USER@greenhouse"
]

Example body: Two projects

json
[
  "YOUR_USER@greenhouse",
  "YOUR_USER@maintenance"
]

Responses

StatusDescription
200ok
401unauthorized
403forbidden