Uploads

Getting bytes in. Every route here hands back a signed URL to PUT to; the file is not real until it is finalized.

Start a cloud import

POST

https://api.genuineai.app/api/v1

/file-imports

Starts the import and returns an id to poll. Files transfer in the background.

Requires any one of media:upload, document:upload, knowledge-base:upload, thread:upload, design:edit, prompt:edit or presentation:edit.

Start a cloud import › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Start a cloud import › Request Body

provider

string · enum · required

Enum values:

dropbox

google-drive

object[] · required

Start a cloud import › Responses

Success

No data returned

Get a cloud import

GET

https://api.genuineai.app/api/v1

/file-imports/{id}

Reports how far a cloud import has got and which files have landed. Imports run in the background, so this is polled rather than waited on.

Requires any one of media:upload, document:upload, knowledge-base:upload, thread:upload, design:edit, prompt:edit or presentation:edit.

Get a cloud import › path Parameters

id

string · uuid · required

Get a cloud import › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Get a cloud import › Responses

Success

No data returned

Finalize an upload

PUT

https://api.genuineai.app/api/v1

/files/{id}/finalize

Step three. Confirms the bytes arrived, which is what admits the file to the library and starts processing — thumbnails, analysis, indexing. A file that is never finalized never appears.

Requires any one of media:edit, document:edit, knowledge-base:write, thread:edit, design:edit, prompt:edit, presentation:edit or task:form:edit.

Finalize an upload › path Parameters

id

string · uuid · required

Finalize an upload › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Finalize an upload › Responses

Success

Anything stored in the workspace: what it is, where its bytes sit, and what is known about it.

File

FileRepo

What the file belongs to. One key naming the owning object, or library for a library it sits in rather than an object it belongs to. Keys the platform stamps (presentation jobs, form submissions, workflow runs) are returned but cannot be sent.

file_id

string · uuid

file_name

string

file_type

string

file_size

integer

file_created

string · date-time

file_updated

string · date-time

file_metadata

object

file_provider_id

string · uuid

file_bucket

string

file_folder

string

file_hash

string

file_status

string

file_added_by

string

file_replicas

string

file_summary

string

file_pref

object

PUT/files/{id}/finalize

curl https://api.genuineai.app/api/v1/files/:id/finalize \
  --request PUT \
  --header 'X-Tenant-Id: <string>' \
  --header 'X-Api-Key: <api-key>'

Example Responses

{
  "file_repo": {
    "library": [
      "media"
    ],
    "ds": "00000000-0000-0000-0000-000000000000",
    "thread": "00000000-0000-0000-0000-000000000000",
    "design": "00000000-0000-0000-0000-000000000000",
    "prompt": "00000000-0000-0000-0000-000000000000",
    "ppt": "00000000-0000-0000-0000-000000000000",
    "ppt_template": "00000000-0000-0000-0000-000000000000",
    "form": "00000000-0000-0000-0000-000000000000",
    "submission": "00000000-0000-0000-0000-000000000000",
    "field": "field",
    "infographic": "00000000-0000-0000-0000-000000000000",
    "sitemap": "00000000-0000-0000-0000-000000000000",
    "node": "00000000-0000-0000-0000-000000000000",
    "wf_instance": "00000000-0000-0000-0000-000000000000",
    "wf_name": "wf_name"
  },
  "file_id": "00000000-0000-0000-0000-000000000000",
  "file_name": "file_name",
  "file_type": "file_type",
  "file_size": 0,
  "file_created": "2024-08-25T15:00:00Z",
  "file_updated": "2024-08-25T15:00:00Z",
  "file_metadata": {},
  "file_provider_id": "00000000-0000-0000-0000-000000000000",
  "file_bucket": "file_bucket",
  "file_folder": "file_folder",
  "file_hash": "file_hash",
  "file_status": "file_status",
  "file_added_by": "file_added_by",
  "file_replicas": "file_replicas",
  "file_summary": "file_summary",
  "file_pref": {}
}

json

application/json

Get a fresh upload URL

PUT

https://api.genuineai.app/api/v1

/files/{id}/update-url

Signed URLs expire. Use this to resume an upload whose URL has gone stale.

Requires any one of media:edit, document:edit, knowledge-base:write, thread:edit, design:edit, prompt:edit, presentation:edit or task:form:edit.

Get a fresh upload URL › path Parameters

id

string · uuid · required

Get a fresh upload URL › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Get a fresh upload URL › Responses

Success

string · uri

A fresh signed URL to PUT the bytes to.

Get upload URLs

POST

https://api.genuineai.app/api/v1

/files/upload-urls

Step one of an upload, and it takes a batch. Returns a signed URL per file; PUT the bytes to it, then finalize each one. The bytes go straight to storage and never through the API.

Requires any one of media:upload, document:upload, knowledge-base:upload, thread:upload, design:edit, prompt:edit or presentation:edit.

Get upload URLs › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Get upload URLs › Request Body

object[] · required

Get upload URLs › Responses

Success

UploadTarget[]

A file record awaiting its bytes, with the signed URL to PUT them to — or, when the file was refused, why.

UploadTarget

file_id

string · uuid

file_name

string

file_type

string

file_size

integer

file_created

string · date-time

file_status

string

file_repo

string

file_metadata

object

file_bucket

string

file_folder

string

file_provider_id

string · uuid

uploadUrl

string · uri

PUT the bytes here, then finalize the file. Absent on a rejected file.

rejection_reason

string

Why this file was not accepted. Absent on an accepted one.

POST/files/upload-urls

curl https://api.genuineai.app/api/v1/files/upload-urls \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant-Id: <string>' \
  --header 'X-Api-Key: <api-key>' \
  --data '{
  "files": [
    {
      "file_name": "file_name",
      "file_type": "file_type",
      "file_size": "file_size",
      "purpose": "media",
      "file_repo": {},
      "file_metadata": {},
      "mediaTags": {},
      "album_ids": [
        "00000000-0000-0000-0000-000000000000"
      ]
    }
  ]
}'

Example Request Body

{
  "files": [
    {
      "file_name": "file_name",
      "file_type": "file_type",
      "file_size": "file_size",
      "purpose": "media",
      "file_repo": {},
      "file_metadata": {},
      "mediaTags": {},
      "album_ids": [
        "00000000-0000-0000-0000-000000000000"
      ]
    }
  ]
}

json

Example Responses

[
  {
    "file_id": "00000000-0000-0000-0000-000000000000",
    "file_name": "file_name",
    "file_type": "file_type",
    "file_size": 0,
    "file_created": "2024-08-25T15:00:00Z",
    "file_status": "file_status",
    "file_repo": "file_repo",
    "file_metadata": {},
    "file_bucket": "file_bucket",
    "file_folder": "file_folder",
    "file_provider_id": "00000000-0000-0000-0000-000000000000",
    "uploadUrl": "https://www.example.com/path/to/resource",
    "rejection_reason": "rejection_reason"
  }
]

json

application/json

Files Stock photos

Start a cloud import

POST

https://api.genuineai.app/api/v1

/file-imports

Starts the import and returns an id to poll. Files transfer in the background.

Requires any one of media:upload, document:upload, knowledge-base:upload, thread:upload, design:edit, prompt:edit or presentation:edit.

Start a cloud import › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Start a cloud import › Request Body

provider

string · enum · required

Enum values:

dropbox

google-drive

object[] · required

Start a cloud import › Responses

Success

No data returned

Get a cloud import

GET

https://api.genuineai.app/api/v1

/file-imports/{id}

Reports how far a cloud import has got and which files have landed. Imports run in the background, so this is polled rather than waited on.

Requires any one of media:upload, document:upload, knowledge-base:upload, thread:upload, design:edit, prompt:edit or presentation:edit.

Get a cloud import › path Parameters

id

string · uuid · required

Get a cloud import › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Get a cloud import › Responses

Success

No data returned

Finalize an upload

PUT

https://api.genuineai.app/api/v1

/files/{id}/finalize

Step three. Confirms the bytes arrived, which is what admits the file to the library and starts processing — thumbnails, analysis, indexing. A file that is never finalized never appears.

Requires any one of media:edit, document:edit, knowledge-base:write, thread:edit, design:edit, prompt:edit, presentation:edit or task:form:edit.

Finalize an upload › path Parameters

id

string · uuid · required

Finalize an upload › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Finalize an upload › Responses

Success

Anything stored in the workspace: what it is, where its bytes sit, and what is known about it.

File

FileRepo

file_id

string · uuid

file_name

string

file_type

string

file_size

integer

file_created

string · date-time

file_updated

string · date-time

file_metadata

object

file_provider_id

string · uuid

file_bucket

string

file_folder

string

file_hash

string

file_status

string

file_added_by

string

file_replicas

string

file_summary

string

file_pref

object

Get a fresh upload URL

PUT

https://api.genuineai.app/api/v1

/files/{id}/update-url

Signed URLs expire. Use this to resume an upload whose URL has gone stale.

Requires any one of media:edit, document:edit, knowledge-base:write, thread:edit, design:edit, prompt:edit, presentation:edit or task:form:edit.

Get a fresh upload URL › path Parameters

id

string · uuid · required

Get a fresh upload URL › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Get a fresh upload URL › Responses

Success

string · uri

A fresh signed URL to PUT the bytes to.

Get upload URLs

POST

https://api.genuineai.app/api/v1

/files/upload-urls

Step one of an upload, and it takes a batch. Returns a signed URL per file; PUT the bytes to it, then finalize each one. The bytes go straight to storage and never through the API.

Requires any one of media:upload, document:upload, knowledge-base:upload, thread:upload, design:edit, prompt:edit or presentation:edit.

Get upload URLs › Headers

X-Tenant-Id

string · uuid · required

The workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.

Get upload URLs › Request Body

object[] · required

Get upload URLs › Responses

Success

UploadTarget[]

A file record awaiting its bytes, with the signed URL to PUT them to — or, when the file was refused, why.

UploadTarget

file_id

string · uuid

file_name

string

file_type

string

file_size

integer

file_created

string · date-time

file_status

string

file_repo

string

file_metadata

object

file_bucket

string

file_folder

string

file_provider_id

string · uuid

uploadUrl

string · uri

PUT the bytes here, then finalize the file. Absent on a rejected file.

rejection_reason

string

Why this file was not accepted. Absent on an accepted one.