post /

Post index

Creates a new element - either a new root level element which is directly owned by the current user, or a new relation, which is created between any two nodes.

Node
Relation

To create a relation, both start and end must be provided together - supplying only one of them is rejected. The two properties are also checked asymmetrically: the current user needs HAS_CREATE_ACCESS on the start node (a new relation is being attached to it), but only HAS_READ_ACCESS on the end node. Both start and end must reference nodes; using the id of an existing relation for either property is rejected.

A handful of types are reserved for internal use (User, Token, Upload) and can not be used as the type of a newly created element, and a handful of properties can not be set directly either - see Reserved data types and Reserved properties.

Request

Node request

curl \
  -H 'Authorization: Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc' \
  -H 'Content-Type: application/json' \
  -d '{
        "type": "Demo",
        "data": {
          "hello": "world :D"
        }
      }' \
  https://api.example.com/
import requests


url = "https://api.example.com/"


payload = {
  "type": "Demo",
  "data": { "hello": "world :D" }
}
headers = {
  "Authorization": "Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc",
  "Content-Type": "application/json"
}


response = requests.post(url, json=payload, headers=headers)


print(response.json())
const url = 'https://api.example.com/';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc',
    'Content-Type': 'application/json'
  },
  body: '{"type":"Demo","data":{"hello":"world :D"}}'
};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
<?php


$client = new \GuzzleHttp\Client();


$response = $client->request('POST', 'https://api.example.com/', [
  'body' => '{"type": "Demo", "data": {"hello": "world :D"}}',
  'headers' => [
    'Authorization' => 'Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc',
    'Content-Type' => 'application/json',
  ],
]);


echo $response->getBody();

Relation request

curl \
  -H 'Authorization: Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc' \
  -H 'Content-Type: application/json' \
  -d '{
        "type": "RELATION",
        "start": "f9a619e1-f3f5-4fbf-a80e-fa8f7dd88103",
        "end": "ecfe46ff-d3c7-4ca7-9b41-9be5476d36e0",
        "data": {
          "hello": "world :D"
        }
      }' \
  https://api.example.com/
import requests


url = "https://api.example.com/"


payload = {
  "type": "RELATION",
  "start": "f9a619e1-f3f5-4fbf-a80e-fa8f7dd88103",
  "end": "ecfe46ff-d3c7-4ca7-9b41-9be5476d36e0",
  "data": { "hello": "world :D" }
}
headers = {
  "Authorization": "Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc",
  "Content-Type": "application/json"
}


response = requests.post(url, json=payload, headers=headers)


print(response.json())
const url = 'https://api.example.com/';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc',
    'Content-Type': 'application/json'
  },
  body: '{"type":"RELATION","start":"f9a619e1-f3f5-4fbf-a80e-fa8f7dd88103","end":"ecfe46ff-d3c7-4ca7-9b41-9be5476d36e0","data":{"hello":"world :D"}}'
};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
<?php


$client = new \GuzzleHttp\Client();


$response = $client->request('POST', 'https://api.example.com/', [
  'body' => '{"type": "RELATION", "start": "f9a619e1-f3f5-4fbf-a80e-fa8f7dd88103", "end": "ecfe46ff-d3c7-4ca7-9b41-9be5476d36e0", "data": {"hello": "world :D"}}',
  'headers' => [
    'Authorization' => 'Bearer secret-token:PIPeJGUt7c00ENn8a5uDlc',
    'Content-Type' => 'application/json',
  ],
]);


echo $response->getBody();

Response

201 · Created

Element was created successfully.

MDN HTTP.dev 

400 · Bad Request

General issues with the user provided request, e.g. missing properties, malformed properties, failing validation logic etc.

MDN HTTP.dev 

401 · Unauthorized

The provided token is either invalid or expired.

MDN HTTP.dev 

404 · Not Found

The referenced parent node does not exist.

MDN HTTP.dev 

response has no body

Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method
Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Location
Allow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Cache-Control: no-cache, private
Location: /455a89b9-4ec7-4b02-b023-bcfbcbba9a9f
X-Powered-By: Ember Nexus API

no schema available

{
  "type": "https://api.example.com/error/400/missing-property",
  "title": "Missing property",
  "status": 400,
  "detail": "Endpoint requires that the request contains property 'type' to be set to a valid type."
}
Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method
Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Location
Allow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Cache-Control: no-cache, private
X-Powered-By: Ember Nexus API
{
  "$schema": "https://spec.openapis.org/oas/3.0/schema/2021-09-28#/definitions/Schema",
  "type": "object",
  "description": "RFC 7807 Problem Details object.",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer"
    },
    "detail": {
      "type": "string"
    }
  }
}
{
  "type": "https://api.example.com/error/401/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authorization for the request failed due to possible problems with the token (incorrect or expired), password (incorrect or changed), the user's unique identifier, or the user's status (e.g., missing, blocked, or deleted)."
}
Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method
Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Location
Allow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Cache-Control: no-cache, private
X-Powered-By: Ember Nexus API
{
  "$schema": "https://spec.openapis.org/oas/3.0/schema/2021-09-28#/definitions/Schema",
  "type": "object",
  "description": "RFC 7807 Problem Details object.",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer"
    },
    "detail": {
      "type": "string"
    }
  }
}
{
  "type": "https://api.example.com/error/404/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Requested element was not found."
}
Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method
Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Location
Allow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Cache-Control: no-cache, private
X-Powered-By: Ember Nexus API
{
  "$schema": "https://spec.openapis.org/oas/3.0/schema/2021-09-28#/definitions/Schema",
  "type": "object",
  "description": "RFC 7807 Problem Details object.",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer"
    },
    "detail": {
      "type": "string"
    }
  }
}

Request Header

Authorization

optional

Bearer token for user authentication. If omitted, the request is processed as an anonymous user; if provided, the associated user account is used.

MDN HTTP.dev Authentication guide 

Request Body

{
  "type": "Demo",
  "id": "f9a619e1-f3f5-4fbf-a80e-fa8f7dd88103",
  "start": "f9a619e1-f3f5-4fbf-a80e-fa8f7dd88103",
  "end": "ecfe46ff-d3c7-4ca7-9b41-9be5476d36e0",
  "data": {
    "hello": "world :D"
  }
}
{
  "type": "object",
  "required": [
    "type",
    "data"
  ],
  "properties": {
    "type": {
      "type": "string",
      "description": "The type of element to be created.",
      "example": "Demo"
    },
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "The element's UUID. Auto-generated if not provided.",
      "example": "f9a619e1-f3f5-4fbf-a80e-fa8f7dd88103"
    },
    "start": {
      "type": "string",
      "format": "uuid",
      "description": "The start node's UUID. Required for relations.",
      "example": "f9a619e1-f3f5-4fbf-a80e-fa8f7dd88103"
    },
    "end": {
      "type": "string",
      "format": "uuid",
      "description": "The end node's UUID. Required for relations.",
      "example": "ecfe46ff-d3c7-4ca7-9b41-9be5476d36e0"
    },
    "data": {
      "type": "object",
      "description": "Arbitrary data related to the element.",
      "additionalProperties": true,
      "example": {
        "hello": "world :D"
      }
    }
  }
}

Response Header

Location

always

URL of the newly created resource.

MDN HTTP.dev 

Access-Control-Allow-Headers

always

Specifies which HTTP headers can be used during a cross-origin request, returned in preflight responses.

MDN HTTP.dev 

Access-Control-Allow-Methods

always

Indicates which HTTP methods are permitted for cross-origin requests, typically returned in preflight responses.

MDN HTTP.dev 

Access-Control-Allow-Origin

always

Specifies which origin(s) may access the resource.

MDN HTTP.dev 

Access-Control-Expose-Headers

always

Lists the response headers that browsers are allowed to access from JavaScript beyond the default restricted set.

MDN HTTP.dev 

Allow

always

Lists the HTTP methods supported by the endpoint; returned alongside a 405 Method Not Allowed response.

MDN HTTP.dev 

Cache-Control

always

Directives controlling caching behavior for the response.

MDN HTTP.dev 

X-Powered-By

always

Identifies the underlying API implementation.

MDN HTTP.dev