FairePlace Property Management API

Media

Endpointhttps://api.faireplace.com/api

Media management (photos, PDF documents)

Upload media and attach to entity

POST

https://api.faireplace.com/api

/media/upload/{entity_type}/{entity_id}

Uploads a file and immediately attaches it to the target entity.

MIME and size validation according to a security level determined by entity_type.
In secure mode (SSE-C), the content is stored encrypted on the S3 side and not returned in plaintext.
The response contains the Media object (not the binary).
Supports tags (comma-separated) and a unique role for the entity.

Upload media and attach to entity › path Parameters

entity_type

string · enum · required

Business entity type supported for media

Enum values:

PLACE

ESTATE

ROOM

EQUIPMENT

LEASE

OWNER

CONTACT

LESSEE

entity_id

string · uuid · required

Upload media and attach to entity › Request Body

file

string · required

The file to upload

tags

string

Comma-separated tags (e.g., photo,primary,facade)

Example: photo,primary

role

string · enum

Unique role of the media for this entity

Enum values:

AVATAR

ID_DOCUMENT

PRIMARY_PHOTO

LEASE_ORIGINAL

LEASE_SIGNED

Example: PRIMARY_PHOTO

Upload media and attach to entity › Responses

Created

id

string | null · uuid

url

string | null

media_type

string | null

MIME type (e.g. application/pdf, image/jpeg)

file_size

integer | null · int64

security_level

string · enum

Security/encryption level. CRITICAL and SENSITIVE may trigger SSE-C encrypted storage; STANDARD is unencrypted.

Enum values:

STANDARD

SENSITIVE

CRITICAL

encryption_key_id

string | null

SSE-C key identifier if the media is encrypted (secure mode)

checksum

string | null

SHA-256 of the source content for integrity verification

tags

array | null

Tags normalized to lowercase; max 32 tags; each tag <= 64 chars, [a-z0-9_-]

roles

array | null

Roles associated with this media for different entities

Enum values:

AVATAR

ID_DOCUMENT

PRIMARY_PHOTO

LEASE_ORIGINAL

LEASE_SIGNED

created_at

string | null · date-time

updated_at

string | null · date-time

POST/media/upload/{entity_type}/{entity_id}

curl --request POST \
  --url https://api.faireplace.com/api/media/upload/:entity_type/:entity_id \
  --header 'Content-Type: multipart/form-data' \
  --form file=file \
  --form 'tags=photo,primary' \
  --form role=PRIMARY_PHOTO

shell

Example Request Body

{
  "file": "file",
  "tags": "photo,primary",
  "role": "PRIMARY_PHOTO"
}

json

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "url": {},
  "media_type": {},
  "file_size": {},
  "security_level": "STANDARD",
  "encryption_key_id": {},
  "checksum": {},
  "tags": {},
  "roles": {},
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z"
}

json

application/json

List media attached to an entity

GET

https://api.faireplace.com/api

/media/{entity_type}/{entity_id}

Returns the Media objects linked to the entity. Encrypted contents are not returned here.

List media attached to an entity › path Parameters

entity_type

string · enum · required

Business entity type supported for media

Enum values:

PLACE

ESTATE

ROOM

EQUIPMENT

LEASE

OWNER

CONTACT

LESSEE

entity_id

string · uuid · required

List media attached to an entity › Responses

object[]

id

string | null · uuid

url

string | null

media_type

string | null

MIME type (e.g. application/pdf, image/jpeg)

file_size

integer | null · int64

security_level

string · enum

Security/encryption level. CRITICAL and SENSITIVE may trigger SSE-C encrypted storage; STANDARD is unencrypted.

Enum values:

STANDARD

SENSITIVE

CRITICAL

encryption_key_id

string | null

SSE-C key identifier if the media is encrypted (secure mode)

checksum

string | null

SHA-256 of the source content for integrity verification

tags

array | null

Tags normalized to lowercase; max 32 tags; each tag <= 64 chars, [a-z0-9_-]

roles

array | null

Roles associated with this media for different entities

Enum values:

AVATAR

ID_DOCUMENT

PRIMARY_PHOTO

LEASE_ORIGINAL

LEASE_SIGNED

created_at

string | null · date-time

updated_at

string | null · date-time

GET/media/{entity_type}/{entity_id}

curl --request GET \
  --url https://api.faireplace.com/api/media/:entity_type/:entity_id

shell

Example Responses

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "url": {},
    "media_type": {},
    "file_size": {},
    "security_level": "STANDARD",
    "encryption_key_id": {},
    "checksum": {},
    "tags": {},
    "roles": {},
    "created_at": "2024-08-25T15:00:00Z",
    "updated_at": "2024-08-25T15:00:00Z"
  }
]

json

application/json

Search media by tags (optionally scoped to an entity)

GET

https://api.faireplace.com/api

/media/search

Searches on tags (TEXT[] + GIN). match_all=true (default) requires that all tags match. Can be restricted to an entity.

Search media by tags (optionally scoped to an entity) › query Parameters

tags

string

Comma-separated list of tags (lowercase)

match_all

boolean

If true (default), all tags must match; else any

entity_type

string · enum

Business entity type supported for media

Enum values:

PLACE

ESTATE

ROOM

EQUIPMENT

LEASE

OWNER

CONTACT

LESSEE

entity_id

string · uuid

Search media by tags (optionally scoped to an entity) › Responses

object[]

id

string | null · uuid

url

string | null

media_type

string | null

MIME type (e.g. application/pdf, image/jpeg)

file_size

integer | null · int64

security_level

string · enum

Security/encryption level. CRITICAL and SENSITIVE may trigger SSE-C encrypted storage; STANDARD is unencrypted.

Enum values:

STANDARD

SENSITIVE

CRITICAL

encryption_key_id

string | null

SSE-C key identifier if the media is encrypted (secure mode)

checksum

string | null

SHA-256 of the source content for integrity verification

tags

array | null

Tags normalized to lowercase; max 32 tags; each tag <= 64 chars, [a-z0-9_-]

roles

array | null

Roles associated with this media for different entities

Enum values:

AVATAR

ID_DOCUMENT

PRIMARY_PHOTO

LEASE_ORIGINAL

LEASE_SIGNED

created_at

string | null · date-time

updated_at

string | null · date-time

GET/media/search

curl --request GET \
  --url https://api.faireplace.com/api/media/search

shell

Example Responses

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "url": {},
    "media_type": {},
    "file_size": {},
    "security_level": "STANDARD",
    "encryption_key_id": {},
    "checksum": {},
    "tags": {},
    "roles": {},
    "created_at": "2024-08-25T15:00:00Z",
    "updated_at": "2024-08-25T15:00:00Z"
  }
]

json

application/json

Replace media tags

PUT

https://api.faireplace.com/api

/media/{id}/tags

Replace media tags › path Parameters

id

string · uuid · required

Replace media tags › Request Body

tags

string[] · required

Replace media tags › Responses

id

string | null · uuid

url

string | null

media_type

string | null

MIME type (e.g. application/pdf, image/jpeg)

file_size

integer | null · int64

security_level

string · enum

Security/encryption level. CRITICAL and SENSITIVE may trigger SSE-C encrypted storage; STANDARD is unencrypted.

Enum values:

STANDARD

SENSITIVE

CRITICAL

encryption_key_id

string | null

SSE-C key identifier if the media is encrypted (secure mode)

checksum

string | null

SHA-256 of the source content for integrity verification

tags

array | null

Tags normalized to lowercase; max 32 tags; each tag <= 64 chars, [a-z0-9_-]

roles

array | null

Roles associated with this media for different entities

Enum values:

AVATAR

ID_DOCUMENT

PRIMARY_PHOTO

LEASE_ORIGINAL

LEASE_SIGNED

created_at

string | null · date-time

updated_at

string | null · date-time

PUT/media/{id}/tags

curl --request PUT \
  --url https://api.faireplace.com/api/media/:id/tags \
  --header 'Content-Type: application/json' \
  --data '
{
  "tags": [
    "string"
  ]
}
'

shell

Example Request Body

{
  "tags": [
    "string"
  ]
}

json

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "url": {},
  "media_type": {},
  "file_size": {},
  "security_level": "STANDARD",
  "encryption_key_id": {},
  "checksum": {},
  "tags": {},
  "roles": {},
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z"
}

json

application/json

Assign a unique role to a media for an entity

PUT

https://api.faireplace.com/api

/media/{entity_type}/{entity_id}/{media_id}/role

Assigns a unique role (ENUM media_role) to a media_id for an entity.

Uniqueness is guaranteed by a partial index (tenant_id, entity_type, entity_id, role).
The body accepts a role corresponding to the MediaRole enum values (AVATAR, ID_DOCUMENT, PRIMARY_PHOTO, LEASE_ORIGINAL, LEASE_SIGNED).
Case-insensitive support for flexibility (e.g., "avatar" or "AVATAR").

Assign a unique role to a media for an entity › path Parameters

entity_type

string · enum · required

Business entity type supported for media

Enum values:

PLACE

ESTATE

ROOM

EQUIPMENT

LEASE

OWNER

CONTACT

LESSEE

entity_id

string · uuid · required

media_id

string · uuid · required

Assign a unique role to a media for an entity › Request Body

role

string · enum · required

Media role (enum MediaRole) - accepts values AVATAR, ID_DOCUMENT, PRIMARY_PHOTO, LEASE_ORIGINAL, LEASE_SIGNED

Enum values:

AVATAR

ID_DOCUMENT

PRIMARY_PHOTO

LEASE_ORIGINAL

LEASE_SIGNED

Example: AVATAR

Assign a unique role to a media for an entity › Responses

No Content

No data returned

PUT/media/{entity_type}/{entity_id}/{media_id}/role

curl --request PUT \
  --url https://api.faireplace.com/api/media/:entity_type/:entity_id/:media_id/role \
  --header 'Content-Type: application/json' \
  --data '
{
  "role": "AVATAR"
}
'

shell

Example Request Body

{
  "role": "AVATAR"
}

json

Example Responses

No example specified for this content type

Get media by role for an entity

GET

https://api.faireplace.com/api

/media/{entity_type}/{entity_id}/role/{role}

Retrieves the Media with the requested role for the entity.

Get media by role for an entity › path Parameters

entity_type

string · enum · required

Business entity type supported for media

Enum values:

PLACE

ESTATE

ROOM

EQUIPMENT

LEASE

OWNER

CONTACT

LESSEE

entity_id

string · uuid · required

role

string · enum · required

Enum values:

AVATAR

ID_DOCUMENT

PRIMARY_PHOTO

LEASE_ORIGINAL

LEASE_SIGNED

Get media by role for an entity › Responses

id

string | null · uuid

url

string | null

media_type

string | null

MIME type (e.g. application/pdf, image/jpeg)

file_size

integer | null · int64

security_level

string · enum

Security/encryption level. CRITICAL and SENSITIVE may trigger SSE-C encrypted storage; STANDARD is unencrypted.

Enum values:

STANDARD

SENSITIVE

CRITICAL

encryption_key_id

string | null

SSE-C key identifier if the media is encrypted (secure mode)

checksum

string | null

SHA-256 of the source content for integrity verification

tags

array | null

Tags normalized to lowercase; max 32 tags; each tag <= 64 chars, [a-z0-9_-]

roles

array | null

Roles associated with this media for different entities

Enum values:

AVATAR

ID_DOCUMENT

PRIMARY_PHOTO

LEASE_ORIGINAL

LEASE_SIGNED

created_at

string | null · date-time

updated_at

string | null · date-time

GET/media/{entity_type}/{entity_id}/role/{role}

curl --request GET \
  --url https://api.faireplace.com/api/media/:entity_type/:entity_id/role/:role

shell

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "url": {},
  "media_type": {},
  "file_size": {},
  "security_level": "STANDARD",
  "encryption_key_id": {},
  "checksum": {},
  "tags": {},
  "roles": {},
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z"
}

json

application/json

Clear role assignment for an entity

DELETE

https://api.faireplace.com/api

/media/{entity_type}/{entity_id}/role/{role}

Removes the role assignment for the given entity.

Clear role assignment for an entity › path Parameters

entity_type

string · enum · required

Business entity type supported for media

Enum values:

PLACE

ESTATE

ROOM

EQUIPMENT

LEASE

OWNER

CONTACT

LESSEE

entity_id

string · uuid · required

role

string · enum · required

Enum values:

AVATAR

ID_DOCUMENT

PRIMARY_PHOTO

LEASE_ORIGINAL

LEASE_SIGNED

Clear role assignment for an entity › Responses

No Content

No data returned

DELETE/media/{entity_type}/{entity_id}/role/{role}

curl --request DELETE \
  --url https://api.faireplace.com/api/media/:entity_type/:entity_id/role/:role

shell

Example Responses

No example specified for this content type

Serve media (JSON for unencrypted, binary for encrypted)

GET

https://api.faireplace.com/api

/media/serve/{id}

If the media is encrypted (SSE-C), the server returns the binary content with server-side decryption and checksum verification.
If not encrypted, returns the Media object (with the S3 URL).

Serve media (JSON for unencrypted, binary for encrypted) › path Parameters

id

string · uuid · required

Serve media (JSON for unencrypted, binary for encrypted) › Responses

id

string | null · uuid

url

string | null

media_type

string | null

MIME type (e.g. application/pdf, image/jpeg)

file_size

integer | null · int64

security_level

string · enum

Security/encryption level. CRITICAL and SENSITIVE may trigger SSE-C encrypted storage; STANDARD is unencrypted.

Enum values:

STANDARD

SENSITIVE

CRITICAL

encryption_key_id

string | null

SSE-C key identifier if the media is encrypted (secure mode)

checksum

string | null

SHA-256 of the source content for integrity verification

tags

array | null

Tags normalized to lowercase; max 32 tags; each tag <= 64 chars, [a-z0-9_-]

roles

array | null

Roles associated with this media for different entities

Enum values:

AVATAR

ID_DOCUMENT

PRIMARY_PHOTO

LEASE_ORIGINAL

LEASE_SIGNED

created_at

string | null · date-time

updated_at

string | null · date-time

GET/media/serve/{id}

curl --request GET \
  --url https://api.faireplace.com/api/media/serve/:id

shell

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "url": {},
  "media_type": {},
  "file_size": {},
  "security_level": "STANDARD",
  "encryption_key_id": {},
  "checksum": {},
  "tags": {},
  "roles": {},
  "created_at": "2024-08-25T15:00:00Z",
  "updated_at": "2024-08-25T15:00:00Z"
}

json

Download media as a binary stream

GET

https://api.faireplace.com/api

/media/download/{id}

Forces the binary download (SSE-C decryption if needed) with Content-Disposition.

Download media as a binary stream › path Parameters

id

string · uuid · required

Download media as a binary stream › Responses

No data returned

GET/media/download/{id}

curl --request GET \
  --url https://api.faireplace.com/api/media/download/:id

shell

Example Responses

No example specified for this content type

application/octet-stream

Delete media (S3 object and DB record)

DELETE

https://api.faireplace.com/api

/media/{id}

Delete media (S3 object and DB record) › path Parameters

id

string · uuid · required

Delete media (S3 object and DB record) › Responses

No Content

No data returned

DELETE/media/{id}

curl --request DELETE \
  --url https://api.faireplace.com/api/media/:id

shell

Example Responses

No example specified for this content type

Serve media for workers (Base64 JSON)

GET

https://api.faireplace.com/api

/media/worker/{id}

Endpoint intended for workers (specific API key/Bearer).

Returns the file in Base64.
Requires X-Tenant-ID and X-Worker-Type.

Serve media for workers (Base64 JSON) › path Parameters

id

string · uuid · required

Serve media for workers (Base64 JSON) › Headers

X-Worker-Type

string · required

Worker type (e.g. signature-processor, otp-validator)

X-Tenant-ID

string · required

Tenant identifier

Serve media for workers (Base64 JSON) › Responses

pdf_base64

string | null

document_name

string | null

content_type

string | null

file_size

integer | null · int64

security_level

string · enum

Security/encryption level. CRITICAL and SENSITIVE may trigger SSE-C encrypted storage; STANDARD is unencrypted.

Enum values:

STANDARD

SENSITIVE

CRITICAL

GET/media/worker/{id}

curl --request GET \
  --url https://api.faireplace.com/api/media/worker/:id \
  --header 'X-Tenant-ID: <string>' \
  --header 'X-Worker-Type: <string>'

shell

Example Responses

{
  "pdf_base64": {},
  "document_name": {},
  "content_type": {},
  "file_size": {},
  "security_level": "STANDARD"
}

json

application/json

Upload signed PDF from worker

POST

https://api.faireplace.com/api

/media/upload-signed/{media_id}

Uploads a signed PDF from a worker. The document is stored in secure mode (SSE-C) with checksum. Returns the metadata of the created signed media.

Upload signed PDF from worker › path Parameters

media_id

string · uuid · required

Upload signed PDF from worker › Headers

X-Tenant-ID

string · required

X-Worker-Type

string · required

Upload signed PDF from worker › Request Body

string

Upload signed PDF from worker › Responses

Created

success

boolean | null

message

string | null

data

object | null

POST/media/upload-signed/{media_id}

curl --request POST \
  --url https://api.faireplace.com/api/media/upload-signed/:media_id \
  --header 'Content-Type: application/pdf' \
  --header 'X-Tenant-ID: <string>' \
  --header 'X-Worker-Type: <string>' \
  --data '"string"'

shell

Example Request Body

"string"

json

Example Responses

{
  "success": {},
  "message": {},
  "data": {}
}

json

application/json

Types Legislative Zones