Get Entity by Foreign ID

Retrieve an entity by its external foreign ID

GET /:projectId/entities/by-foreign-id

Get Entity by Foreign ID

cURL

curl --request GET \
  --url https://api.replyke.com/api/v6/:projectId/entities/by-foreign-id

200

{
  "id": "<string>",
  "projectId": "<string>",
  "foreignId": "<string>",
  "title": "<string>",
  "content": "<string>",
  "keywords": [
    {}
  ],
  "metadata": {},
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

Retrieves a single entity by its foreignId. If the entity does not exist and createIfNotFound=true is provided, a blank entity will be created and returned.

Query Parameters

foreignId · string · required

The external ID used to locate the entity

createIfNotFound · string

If set to true, creates a blank entity if none exists with that foreign ID

Response

id · string

Unique entity identifier

projectId · string

Project identifier

foreignId · string

External reference ID

title · string

Entity title (may be null for newly created entities)

content · string

Entity content (may be null for newly created entities)

keywords · array

Array of keywords

metadata · object

Custom metadata

createdAt · string

Creation timestamp in ISO 8601 format

updatedAt · string

Last update timestamp in ISO 8601 format

Error Responses

Invalid Query - 400 Bad Request

{
  "error": "Missing valid foreignId in request query.",
  "code": "entity/invalid-query-params"
}

Not Found - 404 Not Found

{
  "error": "Entity not found",
  "code": "entity/not-found"
}

Server Error - 500 Internal Server Error

{
  "error": "Internal server error.",
  "code": "entity/server-error",
  "details": "<Error message>"
}

---

Notes

• Authentication is not required.
• This endpoint supports optional automatic entity creation.
• If createIfNotFound is enabled, a webhook is triggered for validation.