Skip to main content
Fetch Entity by Foreign ID
Requires the entities bundle. A project without the entities bundle returns 403 database/tables-not-available. See Bundles.
Returns an entity matching the given 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 profile
  • space — the space the entity belongs to
  • topComments — the entity’s best top-level comments, as full Comment objects (see Top comments)
  • saved — whether the authenticated user has saved this entity
  • files — uploaded file/image attachments
  • grants — 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

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.
include=topComment is rejected with a pointer to its replacement.
Returned when no entity with this foreignId exists and createIfNotFound is not "true".