API Reference
The Fency API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
The Fency API doesn't support bulk updates. You can work on only one object per request.
Authentication
The Fency API uses API keys to authenticate requests. You can view and manage your API keys in the Fency Dashboard.
Your API keys carry many privileges, so be sure to keep them secure! Do not share your API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
Authentication to the API is performed via bearer auth. Provide your API key as -H "Authorization: Bearer <your-api-key>".
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
curl https://api.fency.ai/v1/memories \
-H "Authorization: Bearer <your-api-key>"
Pagination
All top-level API resources have support for bulk fetches through "list" API methods. For example, you can list Memories. These list API methods share a common structure and accept the parameters nextPageToken and previousPageToken.
The nextPageToken parameter returns the items listed after the last item in the current list.
The previousPageToken parameter returns the items listed before the first item in the current list.
These parameters are mutually exclusive. You can use either the nextPageToken or previousPageToken parameter, but not both simultaneously.
curl -X GET https://api.fency.ai/v1/memories?nextPageToken=MjAyNC0wNC0wOF \
-H 'Content-Type: application/json' \
-H 'Authorization : Bearer <your-api-key>'
Webhooks
Webhooks are a way to receive real-time notifications from the API when a specific event occurs. For example, you can receive an event when a memory is created, updated, or deleted.
To start receiving webhook events, create and register a webhook through the dashboard.
Webhook Event Types
See the webhook event types for a list of all available event types.
Webhook Security
A cryptographically secure secret should be generated and persisted on your own server. When you create a webhook in dashboard, the secret must be provided.
We will use the secret to generate a signature on each webhook request, provided in the x-fency-signature header. Seeverifying the payload signature for instructions on using the secret to verify that the request originated from Fency.
Webhook Payload Signature Verification
Requests to your endpoint will bear an x-fency-signature header verifying that the request has come from us.
The signature is the HMAC hex digest of the payload, where the algorithm is sha1, the key is your own secret, and the payload is the raw UTF-8 request body received from us.The signature is then prefixed with sha1=.
A delivery of {"payload":"example"} signed with example-secret would have an x-fency-signature of sha1=e417e6fc2e7f8a78c93a35a7b344d36ce179fc8d.
const secret = "example-secret";
const payload = req.body; // {"payload":"example"}
// Read signature from request HTTP header
const fencySignature = Buffer.from(req.get("x-fency-signature"), "utf8");
// Compute signature using your secret and the request payload
const hmac = crypto.createHmac("sha1", secret);
const digest = Buffer.from("sha1=" + hmac.update(payload).digest("hex"), "utf8");
// Check whether they match, using timing-safe equality (don't use ==)
if (!crypto.timingSafeEqual(digest, fencySignature)) {
throw new Error("Signature invalid");
}
Memories
The memory object represents stored data that can be created, updated, and retrieved. Memories support custom metadata and content that can be used to persist information for your application.
The Memory Object
The unique identifier of the memory.
The timestamp the object was created.
The timestamp when the memory was last updated.
The type identifier for the memory.
The title of the memory.
The full content of the memory.
The synchronization status of the content.
Custom key-value metadata for the memory.
{
"id": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"sourceType": "TEXT",
"typeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"title": "Example Title",
"content": "This is the full content of the secret memory.",
"contentParts": 1,
"contentStatus": "SYNCHRONIZED",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
Create a memory
You can create memories by text, URL, or file upload.
Create memory by text
Creates a memory from plain text content.
The type identifier for the memory.
Set to TEXT.
The title of the memory.
The text content of the memory.
Optional custom key-value metadata for the memory.
curl -X POST https://api.fency.ai/v1/memories \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-api-key>" \
--json '{
"memoryTypeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"sourceType": "TEXT",
"title": "My text memory",
"text": "This is the content of my text memory.",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}'
{
"id": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"sourceType": "TEXT",
"typeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"title": "My text memory",
"content": null,
"contentParts": null,
"contentStatus": "SYNCHRONIZING",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
Create memory by URL
Creates a memory by fetching content from a URL.
The type identifier for the memory.
Set to URL.
The title of the memory.
The URL to fetch content from.
Optional custom key-value metadata for the memory.
curl -X POST https://api.fency.ai/v1/memories \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-api-key>" \
--json '{
"memoryTypeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"sourceType": "URL",
"title": "My URL memory",
"url": "https://example.com/article",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}'
{
"id": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"sourceType": "FILE",
"typeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"title": "My URL memory",
"content": null,
"contentParts": null,
"contentStatus": "SYNCHRONIZING",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
Create memory by file
Creates a memory with file source type. Use the file upload endpoint for multipart uploads.
The type identifier for the memory.
Set to FILE.
The title of the memory.
Optional custom key-value metadata for the memory.
curl -X POST https://api.fency.ai/v1/memories \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-api-key>" \
--json '{
"memoryTypeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"sourceType": "FILE",
"title": "My file memory",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}'
{
"id": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"sourceType": "FILE",
"typeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"title": "My file memory",
"content": null,
"contentParts": null,
"contentStatus": "EMPTY",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
List memories
Returns a list of memories. Supports pagination via nextPageToken and previousPageToken query parameters.
Optional. Token for the next page of results.
Optional. Token for the previous page of results.
curl -X GET https://api.fency.ai/v1/memories \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-api-key>"
{
"items": [
{
"id": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"sourceType": "TEXT",
"typeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"title": "Example Title",
"content": "This is the full content of the secret memory.",
"contentParts": 1,
"contentStatus": "SYNCHRONIZED",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
],
"pagination": {
"previousPageToken": "<remove-me>",
"nextPageToken": "YWNlNGM2NjYtYzRiYi00MDk4LWE2MWItNThlNjNkNTlhM2E3"
}
}
Retrieve a Memory
Retrieves the memory for a unique id.
The unique identifier of the memory.
curl -X GET https://api.fency.ai/v1/memories/:id \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-api-key>"
{
"id": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"sourceType": "TEXT",
"typeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"title": "Example Title",
"content": "This is the full content of the secret memory.",
"contentParts": 1,
"contentStatus": "SYNCHRONIZED",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
Update a Memory
Updates a memory. Only provided fields will be updated.
The unique identifier of the memory.
Optional. The title of the memory.
Optional. Updated text content (for TEXT source type).
Optional. Updated URL (for URL source type).
Optional. Custom key-value metadata for the memory.
curl -X PATCH https://api.fency.ai/v1/memories/:id \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-api-key>" \
--json '{
"title": "Updated Memory Title",
"text": "Updated content for the memory.",
"url": "https://example.com/updated-memory.pdf",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}'
{
"id": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"sourceType": "TEXT",
"typeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"title": "Example Title",
"content": "This is the full content of the secret memory.",
"contentParts": 1,
"contentStatus": "SYNCHRONIZED",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
Delete a Memory
Permanently deletes a memory. This action cannot be undone.
The unique identifier of the memory.
curl -X DELETE https://api.fency.ai/v1/memories/:id \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-api-key>"
Create upload for memory
Creates a presigned upload URL for uploading a file to a memory. First create a memory with sourceType: FILE (see Create memory by file), then call this endpoint with the returned memory ID to get an upload URL.
The unique identifier of the memory.
The name of the file to upload.
The size of the file in bytes.
The MIME type of the file (e.g. application/pdf).
curl -X POST https://api.fency.ai/v1/memories/:id/uploads \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-api-key>" \
--json '{
"fileName": "document.pdf",
"fileSize": 1024,
"mimeType": "application/pdf"
}'
{
"awsS3PostRequest": {
"amzDate": "20231001T000000Z",
"amzSignature": "example-signature",
"amzAlgorithm": "AWS4-HMAC",
"amzCredential": "example-credential",
"policy": "example-policy",
"key": "example-key",
"uploadUrl": "https://example-bucket.s3.amazonaws.com",
"sessionToken": "example-session-token"
}
}
Events
Events are our way of letting you know when something interesting happens in your account. When an interesting event occurs, we create a new event object. For example, when a memory is created, we create an event of type memory.created, and when a memory is updated, we create an event of type memory.updated.
Events contain different data fields depending on its type. For example, a memory.updated event contains the given entity object (the memory) that was updated.
We have a separate webhooks system for sending the Event objects directly to an endpoint on your server. You can manage webhooks in your account dashboard.
We only guarantee access to the events through the API and dashboard for 30 days.
memory.created
Event published when a new memory is created.
The unique identifier of the event.
The version of the event.
The type of the event.
The timestamp the event was created.
The unique identifier of the organization that the event belongs to.
The memory that was created.
{
"id": "evt_123e4567e89b12d3a456426614174000",
"type": "memory.created",
"createdAt": "2023-10-01T12:00:00Z",
"entity": {
"id": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"sourceType": "TEXT",
"typeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"title": "Example Title",
"content": "This is the full content of the secret memory.",
"contentParts": 1,
"contentStatus": "SYNCHRONIZED",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
}
memory.updated
Event published when a memory is updated.
The unique identifier of the event.
The version of the event.
The type of the event.
The timestamp the event was created.
The unique identifier of the organization that the event belongs to.
The memory that was updated.
{
"id": "evt_123e4567e89b12d3a456426614174000",
"type": "memory.updated",
"createdAt": "2023-10-01T12:00:00Z",
"entity": {
"id": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"sourceType": "TEXT",
"typeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"title": "Example Title",
"content": "This is the full content of the secret memory.",
"contentParts": 1,
"contentStatus": "SYNCHRONIZED",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
}
memory.deleted
Event published when a memory is deleted.
The unique identifier of the event.
The version of the event.
The type of the event.
The timestamp the event was created.
The unique identifier of the organization that the event belongs to.
The memory that was deleted.
{
"id": "evt_123e4567e89b12d3a456426614174000",
"type": "memory.deleted",
"createdAt": "2023-10-01T12:00:00Z",
"entity": {
"id": "mem_cf4fe6caa10b4009a8b103d2d5d64042",
"createdAt": "2024-04-08T17:02:27.887295Z",
"updatedAt": "2024-04-08T17:02:27.887295Z",
"sourceType": "TEXT",
"typeId": "mty_cf4fe6caa10b4009a8b103d2d5d64042",
"title": "Example Title",
"content": "This is the full content of the secret memory.",
"contentParts": 1,
"contentStatus": "SYNCHRONIZED",
"metadata": {
"organization_id": "org_1234567890",
"allowed_roles": [
"Admin",
"Member"
],
"size": 1337,
"is_available": true,
"mean_score": 3.14
}
}
}