Fetch Entity by Foreign ID
curl --request GET \
--url https://api.sublay.io/v8/:projectId/entities/by-foreign-id \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.sublay.io/v8/:projectId/entities/by-foreign-id"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.sublay.io/v8/:projectId/entities/by-foreign-id', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sublay.io/v8/:projectId/entities/by-foreign-id",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.sublay.io/v8/:projectId/entities/by-foreign-id"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.sublay.io/v8/:projectId/entities/by-foreign-id")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sublay.io/v8/:projectId/entities/by-foreign-id")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyEntity Endpoints
Fetch Entity by Foreign ID
Get an entity by its foreign ID, optionally creating it if not found
Fetch Entity by Foreign ID
curl --request GET \
--url https://api.sublay.io/v8/:projectId/entities/by-foreign-id \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.sublay.io/v8/:projectId/entities/by-foreign-id"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.sublay.io/v8/:projectId/entities/by-foreign-id', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sublay.io/v8/:projectId/entities/by-foreign-id",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.sublay.io/v8/:projectId/entities/by-foreign-id"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.sublay.io/v8/:projectId/entities/by-foreign-id")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sublay.io/v8/:projectId/entities/by-foreign-id")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyRequires the
entities bundle. A project without the entities bundle returns 403 database/tables-not-available. See Bundles.foreignId within the project. Optionally creates a blank entity if none exists — useful for automatically bootstrapping entities when a user first visits a page or URL in your application.
Query Parameters
string
required
The foreign ID to look up. This is the identifier from your application (URL, slug, database ID, etc.).
string
When
"true", creates a blank entity with this foreignId if no entity is found. The new entity has no title, content, or user attribution. Defaults to "false".string
Associations to include. Pass it as one comma-separated value (
include=user,space) or as repeated params (include=user&include=space). Values:user— the author’s user profilespace— the space the entity belongs totopComments— the entity’s best top-level comments, as full Comment objects (see Top comments)saved— whether the authenticated user has saved this entityfiles— uploaded file/image attachmentsgrants— the reputation-grant summary for the entity
number
default:"1"
With
include=topComments: how many top comments per entity. A whole number of at least 1 — 0, a negative number or a non-integer value returns 400 entity/invalid-query. Maximum 5 — larger values are treated as 5.string
default:"upvote"
With
include=topComments: the reaction whose raw count ranks the top comments (ties newest first). One of upvote, downvote, like, love, wow, sad, angry, funny.include values are case-insensitive. An unknown value returns 400 entity/invalid-query, as does sending topCommentsLimit or topCommentsSortByReaction without include=topComments. topComments lists real content only — deleted, removed and block-edged comments are left out — and is [] when nothing qualifies.
Response
Returns an Entity object.This endpoint returns entities regardless of moderation status, so the client can display the appropriate moderation state. Draft entities are only returned to their author (or with a service/master key).
Error Responses
Invalid include — 400
Invalid include — 400
Returned with code
entity/invalid-query for an unknown include value, when topCommentsLimit is below 1 or not a whole number, or when topCommentsLimit / topCommentsSortByReaction is sent without include=topComments.{ "error": "include: Unknown include `comments`. Allowed: user, space, topComments, saved, files, grants.", "code": "entity/invalid-query" }
Renamed include — 400
Renamed include — 400
include=topComment is rejected with a pointer to its replacement.{
"error": "`include=topComment` was renamed to `topComments` (with `topCommentsLimit` / `topCommentsSortByReaction`).",
"code": "entity/unsupported-param",
"param": "include"
}
Not Found — 404
Not Found — 404
{ "error": "Entity not found", "code": "entity/not-found" }
foreignId exists and createIfNotFound is not "true".
