Push Api

The @unbody-io/push-api package provides an easy-to-use interface to manually upload files and push custom data into your projects.

Uploading Files: Manually upload and manage files like images and videos.
Pushing Custom Data: Push structured JSON data with your own schema. Learn more about custom schema.

Installation

Install PushApi using your preferred package manager.

npm install @unbody-io/push-api

yarn add @unbody-io/push-api

pnpm add @unbody-io/push-api

Authentication

The Push API requires three credentials for authentication:

import { UnbodyPushAPI } from '@unbody-io/push-api'
 
const pushApi = new UnbodyPushAPI({
  projectId: '[project-id]',      
  sourceId: '[source-id]',        
  auth: {
    apiKey: 'pk_...',           
  },
})

Getting Credentials

projectId: Settings menu
sourceId: Create Push API source using Admin API
apiKey: Settings → Developer Settings → Create API key

⚠️

Store credentials securely using environment variables

Usage

Upload Files

You can upload files to your Unbody project using the .files.upload() method. The file should have a valid name and extension.

// Uploading a file
const { data } = await pushApi.files.upload({
  id: 'file-uuid', // Unique ID for the file
  file: file, // File object
  payload: {}, // Extra fields for the file (optional)
})
 
// Example response data
console.log(data.data.collection) // E.g., 'ImageBlock' for image files
console.log(data.data.id) // Unique file ID
console.log(data.data.contentType) // File's content type
 
// Or, with external URL
const { data } = await pushApi.files.upload({
  id: 'file-uuid',
  filename: 'image.jpg', // required
  url: 'https://example.com/image.jpg',
  payload: {}, // Extra fields for the file (optional)
})

Alternatively, you can also upload a file using a FormData object:

const formData = new FormData()
 
formData.append('id', 'file-unique-id')
formData.append('file', file, 'file-name.ext')
formData.append(
  'payload',
  JSON.stringify({
    xCustomField: 'value',
  }),
)
 
await pushApi.files.upload({
  form: formData, // FormData object with file and id
})

Delete Files

To delete a file, use the .files.delete() method:

await pushApi.files.delete({
  id: 'file-unique-id', // Unique ID for the file
})

List Files

You can list uploaded files with pagination options:

await pushApi.files.list({
  cursor: 'cursor', // Optional
  limit: 10, // Optional
  offset: 0, // Optional
  sort: 'asc', // Optional
})

Create Data Records

To create a custom data record, use the .records.create() method. This is useful for pushing structured JSON data to your Unbody project.

await pushApi.records.create({
  id: 'record-custom-id', // Unique ID for the record
  collection: 'CustomCollection', // Collection name
  payload: {}, // Record payload
})

Get Data Records

To fetch a specific data record by its ID:

const { data } = await pushApi.records.get({
  id: 'record-unique-id',
})
 
console.log(data.data.collection) // Record collection name
console.log(data.data.id) // Record ID
console.log(data.data.type) // Record type; `file` or `record`

Update Records

The .records.update() method allows you to replace the entire payload of a record or file’s extra fields:

await pushApi.records.update({
  id: 'record-unique-id',
  collection: 'CustomCollection',
  payload: {}, // New payload, replaces the existing payload
})
 
await pushApi.records.update({
  id: 'file-unique-id',
  collection: 'TextDocument',
  payload: {
    xCustomField: 'value',
  }, // New payload, replaces the existing payload
})

Patch Records

The .records.patch() method lets you partially update the record’s payload or file’s extra fields:

await pushApi.records.patch({
  id: 'record-unique-id',
  collection: 'CustomCollection',
  payload: {}, // Partial update, merges with the existing payload
})
 
await pushApi.records.patch({
  id: 'file-unique-id',
  collection: 'TextDocument',
  payload: {
    xCustomField: 'new value',
  }, // Partial update, merges with the existing payload
})

Cross-References

await pushApi.records.patch({
  id: 'record-unique-id',
  collection: 'CustomCollection',
  payload: {
    profilePhoto: [
      {
        id: 'image-file-id',
        collection: 'ImageBlock',
      },
    ],
  },
})

Delete Data Records

To delete a specific data record:

await pushApi.records.delete({
  id: 'record-unique-id',
  collection: 'CustomCollection',
})

This method cannot be used to delete files. For deleting files, use pushApi.files.delete method instead.

List Data Records

You can list all records in a specific collection:

await pushApi.records.list({
  collection: 'CustomCollection', // Optional
  cursor: 'cursor', // Optional
  limit: 10, // Optional
  offset: 0, // Optional
})

Notes

The id for both files and records must be unique across the same source. For instance, a file and a record cannot share the same id. When processing records through the Push API, the remoteId field will contain this id.
Data within a source is isolated, meaning cross-references cannot be created between records or files that belong to different sources. All operations are limited to the current source.

Before using the Push API source, initialize ite after making any changes. Learn more about Admin API source documentation.

Endpoints

The following is a summary of the main endpoints and their corresponding response types:

Files

Upload File: .files.upload()
Response: FileRecordEntity
Delete File: .files.delete()
Response: FileRecordEntity
List Files: .files.list()
Response: { files: FileRecordEntity[], cursor: string }

Data Records

Create Record: .records.create()
Response: DataRecordEntity
Get Record: .records.get()
Response: RecordEntity
Update Record: .records.update()
Response: DataRecordEntity
Patch Record: .records.patch()
Response: DataRecordEntity
Delete Record: .records.delete()
Response: DataRecordEntity
List Records: .records.list()
Response: { records: RecordEntity[], cursor: string }

Prebuilt Integrations Overview