Skip to main content
POST
/
:projectId
/
api
/
v7
/
entities
Create Entity
curl --request POST \
  --url https://api.replyke.com/api/v6/:projectId/api/v7/entities \
  --header 'Content-Type: application/json' \
  --data '
{
  "foreignId": "<string>",
  "sourceId": "<string>",
  "spaceId": "<string>",
  "userId": "<string>",
  "title": "<string>",
  "content": "<string>",
  "attachments": [
    {}
  ],
  "keywords": [
    "<string>"
  ],
  "mentions": [
    {}
  ],
  "location": {},
  "metadata": {},
  "isDraft": true,
  "excludeUserId": true,
  "requireUser": true,
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "images.files": [
    null
  ],
  "images.options": "<string>",
  "files.files": [
    null
  ],
  "files.options": "<string>"
}
'
Creates a new entity in your project. Supports optional file uploads via multipart/form-data. When no files are attached, use application/json. The entity is attributed to the authenticated user unless excludeUserId is set.

​
Body Parameters

​
foreignId
string
Your application’s identifier for this entity (URL, slug, database ID, etc.). Used to fetch or create entities without knowing the Replyke ID.
​
sourceId
string
Groups entities by source. Use a topic ID or page ID to scope feeds to a specific context.
​
spaceId
string
The ID of the space this entity belongs to. The space must exist in the same project.
​
userId
string
Attribute the entity to a specific user. Must match the authenticated user ID unless the request uses a service or master key.
​
title
string
A title or headline for the entity.
​
content
string
The main body text of the entity.
​
attachments
object[]
An array of generic attachment objects. Each item is a free-form JSON object — structure is defined by your application.
​
keywords
string[]
Tags or keywords associated with this entity. Used for keyword-based filtering in the list endpoint.
​
mentions
object[]
Users or spaces mentioned in this entity. Each object is a discriminated union:
  • { type: "user", id: string, username: string, foreignId?: string }
  • { type: "space", id: string, slug: string }
Mentioned users receive an in-app notification.
​
location
object
Geographic coordinates for this entity. Enables proximity-based filtering.
{ "latitude": 40.7128, "longitude": -74.0060 }
​
metadata
object
A free-form JSON object for any custom data your application needs alongside the entity. Supports rich filtering via metadataFilters in the list endpoint.
​
isDraft
boolean
When true, the entity is saved as a draft and excluded from public feeds. Publish it later via the Publish Entity endpoint.
​
excludeUserId
boolean
When true, the entity is created without user attribution even if a user is authenticated.
​
requireUser
boolean
When true, returns 401 if no user is authenticated.
​
createdAt
string
ISO 8601 datetime to backfill a creation timestamp. Service or master key only.
​
updatedAt
string
ISO 8601 datetime for updatedAt. Requires createdAt to also be set. Must be ≥ createdAt. Service or master key only.

​
File Uploads (multipart/form-data)

When uploading files, send the request as multipart/form-data. All JSON fields above are sent as form fields.
​
images.files
file[]
Image files to attach. Maximum 10 images, 50 MB each. Must be valid images. Requires images.options.
​
images.options
string
Stringified JSON describing how to process uploaded images. Must include a mode field:
  • "exact-dimensions" — resize to specific pixel dimensions per variant
  • "aspect-ratio-width-based" — resize by width maintaining aspect ratio
  • "aspect-ratio-height-based" — resize by height maintaining aspect ratio
  • "original-aspect" — preserve original ratio, resize by max dimension
  • "multi-aspect-ratio" — generate crops at multiple aspect ratios
Optional fields: quality (1–100), format (webp, jpeg, png, original), stripExif (boolean), pathParts (string[]).
​
files.files
file[]
Generic files to attach. Maximum 10 files, 50 MB each.
​
files.options
string
Stringified JSON for file options. Optional pathParts (string[]) customizes the storage path.

​
Response

Returns the created Entity object. When files are uploaded, the entity includes a files array with signed URLs for each attachment.
Draft entities are invisible to all users until published. Use Fetch Drafts to list an author’s unpublished drafts.

​
Error Responses

{ "error": "Authentication required to create this entity.", "code": "entity/user-required" }

{ "error": "User is not authorized to create this entity.", "code": "entity/unauthorized" }

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

{ "error": "Cannot set updatedAt without also setting createdAt.", "code": "entity/invalid-timestamp" }
Also returned when updatedAt is earlier than createdAt:
{ "error": "updatedAt must be the same or after createdAt.", "code": "entity/invalid-timestamp" }

{ "code": "entity/file-too-large", "message": "Image \"photo.jpg\" exceeds 50MB limit." }

{ "code": "entity/invalid-image", "message": "File \"doc.txt\" is not a valid image: ..." }