# Introduction

The Whaly API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The Whaly API doesn't support bulk updates. You can work on only one object per request.


# API Endpoint

Each organization has its own API endpoint. This endpoint can be found in the API section of your Whaly settings.

Whaly API endpoints have the following format:

```
https://{orgSlug}.my.whaly.io
```


# Authentication

The Whaly API uses Service Account Secret Keys to authenticate requests. You can view and manage your Secret keys in your Whaly settings panel.

Secret keys have the prefix `sk` . In order to grant proper access control to your Secret Keys, you should manage the roles and sharings of the attached Service Account.

{% hint style="warning" %}
Your Secret keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
{% endhint %}

Authentication to the API is performed via **HTTP Bearer Auth**. Provide your Secret key as the Bearer value in your Authorization header.

Example of curl option would be `-H "Authorization: Bearer sk:4eC39HqLyjWDarjtT1zdp7dc"` 

All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls made over plain HTTP will fail. API requests without authentication will also fail.


# Errors

Whaly uses conventional HTTP response codes to indicate the success or failure of an API request. In general: 

* Codes in the `2xx` range indicate success.
* Codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted, an invalid value was provided, etc.). 
* Codes in the `5xx` range indicate an error with Whaly's servers (these are rare).

Every time that Whaly API is returning an Error, the following schema is used:

```json
{
    "status_code": 401, // The status code of the response
    "message": "Unauthorized", // A detailed explanation of the error
    "request_id": "20256c3e71efa5aa267df84eb9c129e5" // The RequestID that you can share with your support contact to troubleshoot the issue
}
```

## HTTP Status code summary

| 200 - OK                           | Everything worked as expected.                                                                                                        |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| 400 - Bad Request                  | The request was unacceptable, often due to missing a required parameter.                                                              |
| 401 - Unauthorized                 | No valid Secret key provided.                                                                                                         |
| 403 - Forbidden                    | The Secret key doesn't have permissions to perform the request.                                                                       |
| 404 - Not Found                    | The requested resource doesn't exist.                                                                                                 |
| 429 - Too Many Requests            | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. [See: Rate Limiting](/rate-limiting) |
| 500, 502, 503, 504 - Server Errors | Something went wrong on Whaly's end. (These are rare.)                                                                                |


# Rate Limiting

To ensure a smooth experience for all Users, all our endpoint have a quota of number of requests per minute that your Service Account can make. If you go beyond this threshold, the request will return a 429 Error (Too Many requests)

The rate limit is based on Service Account and can differ per endpoint. 

By default, all endpoints have a quota of **500 requests per minute**. If an endpoint have a different quota, it is documented on its reference page.

## Rate limit Headers

Every API request returns header contains the following fields:

`X-RateLimit-Limit`: *Quota limit for this endpoint* \
`X-RateLimit-Remaining`: *Number of remaining API calls that you can do before a quota reset*\
`X-RateLimit-Reset`: *Number of seconds before the quota is reset to the limit*

In case of 429 errors, an additional Header is added to the response:

`Retry-After`: Number of seconds that you should wait before retrying the call to see it succeed.


# Pagination

All top-level API resources have support for bulk fetches via "list" API methods. For instance, you can list Users, list Portals, and list Roles. These list API methods share a common structure, taking at least these two parameters: limit, after.

The response of a list API method represents a single page in a chronological stream of objects. If you do not specify `after`, you will receive the first page of this stream, containing the oldest objects. 

In each page, the value to be used to get to the next page in the `after` parameter is supplied.

See an example of paginated response that returns 2 items:

```json
{
    "data": [
        {
            "id": "ro_ZW9dbXgfX2L0Dg",
            "name": "Admin Builder",
            "is_system": true
        },
        {
            "id": "ro_3zrr1XRrXMyYG6",
            "name": "Builder",
            "is_system": true
        }
    ],
    "paging": {
        "next": {
            "after": "MQit=" // This should be the value to use in the `after` parameter to get to the next page
        }
    }
}
```

You are at the end of the pages when the `after` parameter is not longer returned in the responses.


# Request IDs

Each API request has an associated request identifier. You can find this value in the response headers, under `X-Request-Id`.  In case of Errors, the Request ID is also included in the body of the response.

If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.


# API reference


# Partner portals

## GET /v1/partner-portals

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"PaginatedListWrapper":{"type":"object","properties":{"paging":{"$ref":"#/components/schemas/PagingInfo"}},"required":["paging"]},"PagingInfo":{"type":"object","properties":{"next":{"$ref":"#/components/schemas/PagingNext"}},"required":["next"]},"PagingNext":{"type":"object","properties":{"after":{"type":"string"}},"required":["after"]},"PartnerPortalDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}}},"paths":{"/v1/partner-portals":{"get":{"operationId":"PortalsController_listAllPortals","parameters":[{"name":"after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedListWrapper"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PartnerPortalDto"}}}}]}}}}}}}}}
```

## GET /v1/partner-portals/{portalId}

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"PartnerPortalDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}}},"paths":{"/v1/partner-portals/{portalId}":{"get":{"operationId":"PortalsController_findOnePortal","parameters":[{"name":"portalId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerPortalDto"}}}}}}}}}
```


# Users

## GET /v1/partner-portals/{portalId}/users

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"PaginatedListWrapper":{"type":"object","properties":{"paging":{"$ref":"#/components/schemas/PagingInfo"}},"required":["paging"]},"PagingInfo":{"type":"object","properties":{"next":{"$ref":"#/components/schemas/PagingNext"}},"required":["next"]},"PagingNext":{"type":"object","properties":{"after":{"type":"string"}},"required":["after"]},"PartnerPortalUserDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID for the Portal User."},"first_name":{"type":"string","description":"First name of the User."},"last_name":{"type":"string","description":"Last name of the User."},"email":{"type":"string","description":"Email of the User."},"last_logged_at":{"type":"string","description":"Last login date and time of the user (ISO 8601 format)"}},"required":["id","first_name","last_name","email","last_logged_at"]}}},"paths":{"/v1/partner-portals/{portalId}/users":{"get":{"operationId":"PortalsController_listAllPortalUsers","parameters":[{"name":"after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"number"}},{"name":"portalId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedListWrapper"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PartnerPortalUserDto"}}}}]}}}}}}}}}
```

## GET /v1/partner-portals/{portalId}/users/{userId}

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"PartnerPortalUserDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID for the Portal User."},"first_name":{"type":"string","description":"First name of the User."},"last_name":{"type":"string","description":"Last name of the User."},"email":{"type":"string","description":"Email of the User."},"last_logged_at":{"type":"string","description":"Last login date and time of the user (ISO 8601 format)"}},"required":["id","first_name","last_name","email","last_logged_at"]}}},"paths":{"/v1/partner-portals/{portalId}/users/{userId}":{"get":{"operationId":"PortalsController_findOnePortalUser","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}},{"name":"portalId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerPortalUserDto"}}}}}}}}}
```

## POST /v1/partner-portals/{portalId}/users

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"CreatePartnerPortalUserDto":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string"},"password":{"type":"string","description":"When set, this will be the password of the User that he/she can use at the first connection."},"roles":{"description":"Contains the list of Role Ids that should be granted to this Portal User","type":"array","items":{"type":"string"}},"locale":{"type":"string","default":"en_US","description":"User locale, used for time and numbers formatting."},"attributes":{"type":"array","description":"When set, this will define the user attributes on its creation.","items":{"type":"object","properties":{"id":{"type":"string"},"value":{"type":"string"}}}}},"required":["first_name","last_name","email","roles"]},"PartnerPortalUserDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID for the Portal User."},"first_name":{"type":"string","description":"First name of the User."},"last_name":{"type":"string","description":"Last name of the User."},"email":{"type":"string","description":"Email of the User."},"last_logged_at":{"type":"string","description":"Last login date and time of the user (ISO 8601 format)"}},"required":["id","first_name","last_name","email","last_logged_at"]}}},"paths":{"/v1/partner-portals/{portalId}/users":{"post":{"operationId":"PortalsController_createPortalUsers","parameters":[{"name":"portalId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePartnerPortalUserDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerPortalUserDto"}}}}}}}}}
```

## DELETE /v1/partner-portals/{portalId}/users/{userId}

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"PartnerPortalUserDeleteResultDto":{"type":"object","properties":{"id":{"type":"string"},"isDeleted":{"type":"boolean"}},"required":["id","isDeleted"]}}},"paths":{"/v1/partner-portals/{portalId}/users/{userId}":{"delete":{"operationId":"PortalsController_deleteOnePortalUser","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}},{"name":"portalId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerPortalUserDeleteResultDto"}}}}}}}}}
```


# User attributes

## GET /v1/user-attributes

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"PaginatedListWrapper":{"type":"object","properties":{"paging":{"$ref":"#/components/schemas/PagingInfo"}},"required":["paging"]},"PagingInfo":{"type":"object","properties":{"next":{"$ref":"#/components/schemas/PagingNext"}},"required":["next"]},"PagingNext":{"type":"object","properties":{"after":{"type":"string"}},"required":["after"]},"UserAttributeDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"name":{"type":"string","description":"Name of User Attribute"},"label":{"type":"string","description":"Human friendly label for User Attribute"},"type":{"type":"string","description":"Type of the User Attribute","enum":["STRING","BOOLEAN","NUMBER","TIME","UNKNOWN"]},"allow_multiple_values":{"type":"boolean","description":"If true, a User can have multiple values for this User Attribute"}},"required":["id","name","label","type","allow_multiple_values"]}}},"paths":{"/v1/user-attributes":{"get":{"operationId":"UserAttributesController_listAll","parameters":[{"name":"after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedListWrapper"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UserAttributeDto"}}}}]}}}}}}}}}
```

## GET /v1/user-attributes/{userAttributeId}

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"UserAttributeDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"name":{"type":"string","description":"Name of User Attribute"},"label":{"type":"string","description":"Human friendly label for User Attribute"},"type":{"type":"string","description":"Type of the User Attribute","enum":["STRING","BOOLEAN","NUMBER","TIME","UNKNOWN"]},"allow_multiple_values":{"type":"boolean","description":"If true, a User can have multiple values for this User Attribute"}},"required":["id","name","label","type","allow_multiple_values"]}}},"paths":{"/v1/user-attributes/{userAttributeId}":{"get":{"operationId":"UserAttributesController_findOne","parameters":[{"name":"userAttributeId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserAttributeDto"}}}}}}}}}
```


# Roles

## GET /v1/roles

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"PaginatedListWrapper":{"type":"object","properties":{"paging":{"$ref":"#/components/schemas/PagingInfo"}},"required":["paging"]},"PagingInfo":{"type":"object","properties":{"next":{"$ref":"#/components/schemas/PagingNext"}},"required":["next"]},"PagingNext":{"type":"object","properties":{"after":{"type":"string"}},"required":["after"]},"RoleDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"name":{"type":"string","description":"Name of Role"},"is_system":{"type":"boolean","description":"If true, this a Role defined and managed by the system."}},"required":["id","name","is_system"]}}},"paths":{"/v1/roles":{"get":{"operationId":"RolesController_listAll","parameters":[{"name":"after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedListWrapper"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RoleDto"}}}}]}}}}}}}}}
```

## GET /v1/roles/{roleId}

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"RoleDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"name":{"type":"string","description":"Name of Role"},"is_system":{"type":"boolean","description":"If true, this a Role defined and managed by the system."}},"required":["id","name","is_system"]}}},"paths":{"/v1/roles/{roleId}":{"get":{"operationId":"RolesController_findOne","parameters":[{"name":"roleId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleDto"}}}}}}}}}
```


# Warehouses

## GET /v1/warehouses

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"PaginatedListWrapper":{"type":"object","properties":{"paging":{"$ref":"#/components/schemas/PagingInfo"}},"required":["paging"]},"PagingInfo":{"type":"object","properties":{"next":{"$ref":"#/components/schemas/PagingNext"}},"required":["next"]},"PagingNext":{"type":"object","properties":{"after":{"type":"string"}},"required":["after"]},"WarehouseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"name":{"type":"string","description":"Name of Warehouse"},"is_managed":{"type":"boolean","description":"If true, it means that this Warehouse is provided by Whaly, so access is limited."},"is_bi_enabled":{"type":"boolean","description":"If true, it means that BI is enabled on this Warehouse."},"is_data_loading_enabled":{"type":"boolean","description":"If true, it means that Connectors are enabled on this Warehouse."},"is_persistence_engine_enabled":{"type":"boolean","description":"If true, it means that Persistence Engine is enabled on this Warehouse."},"warehouse_type":{"type":"string","description":"Type of the Warehouse","enum":["BIGQUERY","SNOWFLAKE","POSTGRES","REDSHIFT","UNKNOWN"]}},"required":["id","name","is_managed","is_bi_enabled","is_data_loading_enabled","is_persistence_engine_enabled","warehouse_type"]}}},"paths":{"/v1/warehouses":{"get":{"operationId":"WarehousesController_listAll","parameters":[{"name":"after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedListWrapper"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WarehouseDto"}}}}]}}}}}}}}}
```

## GET /v1/warehouses/{warehouseId}

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"WarehouseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"name":{"type":"string","description":"Name of Warehouse"},"is_managed":{"type":"boolean","description":"If true, it means that this Warehouse is provided by Whaly, so access is limited."},"is_bi_enabled":{"type":"boolean","description":"If true, it means that BI is enabled on this Warehouse."},"is_data_loading_enabled":{"type":"boolean","description":"If true, it means that Connectors are enabled on this Warehouse."},"is_persistence_engine_enabled":{"type":"boolean","description":"If true, it means that Persistence Engine is enabled on this Warehouse."},"warehouse_type":{"type":"string","description":"Type of the Warehouse","enum":["BIGQUERY","SNOWFLAKE","POSTGRES","REDSHIFT","UNKNOWN"]}},"required":["id","name","is_managed","is_bi_enabled","is_data_loading_enabled","is_persistence_engine_enabled","warehouse_type"]}}},"paths":{"/v1/warehouses/{warehouseId}":{"get":{"operationId":"WarehousesController_findOne","parameters":[{"name":"warehouseId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseDto"}}}}}}}}}
```


# Persistence Engine

## POST /v1/warehouses/{warehouseId}/persistence-engine/run

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"RunPersistenceEngineDto":{"type":"object","properties":{}},"WarehouseDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"name":{"type":"string","description":"Name of Warehouse"},"is_managed":{"type":"boolean","description":"If true, it means that this Warehouse is provided by Whaly, so access is limited."},"is_bi_enabled":{"type":"boolean","description":"If true, it means that BI is enabled on this Warehouse."},"is_data_loading_enabled":{"type":"boolean","description":"If true, it means that Connectors are enabled on this Warehouse."},"is_persistence_engine_enabled":{"type":"boolean","description":"If true, it means that Persistence Engine is enabled on this Warehouse."},"warehouse_type":{"type":"string","description":"Type of the Warehouse","enum":["BIGQUERY","SNOWFLAKE","POSTGRES","REDSHIFT","UNKNOWN"]}},"required":["id","name","is_managed","is_bi_enabled","is_data_loading_enabled","is_persistence_engine_enabled","warehouse_type"]}}},"paths":{"/v1/warehouses/{warehouseId}/persistence-engine/run":{"post":{"operationId":"WarehousesController_runPersistenceEngine","parameters":[{"name":"warehouseId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunPersistenceEngineDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseDto"}}}}}}}}}
```


# Documents

## GET /v1/documents

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"PaginatedListWrapper":{"type":"object","properties":{"paging":{"$ref":"#/components/schemas/PagingInfo"}},"required":["paging"]},"PagingInfo":{"type":"object","properties":{"next":{"$ref":"#/components/schemas/PagingNext"}},"required":["next"]},"PagingNext":{"type":"object","properties":{"after":{"type":"string"}},"required":["after"]},"DocumentDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"file_name":{"type":"string","description":"A user friendly name for the document"},"external_id":{"type":"string","description":"The id generated by the system of referenced"},"original_file_name":{"type":"string","description":"The file name as of the extracted file.","nullable":true},"original_file_path":{"type":"string","description":"The file path of the extracted file.","nullable":true},"original_author":{"type":"string","description":"The author of the document.","nullable":true},"extension":{"type":"string","description":"The file extension."},"file_path":{"type":"string","description":"The file path as stored in the object storage."},"valid_from":{"type":"string","description":"The date at which the document has been made available.","nullable":true},"valid_until":{"type":"string","description":"The date at which the document will be made unavailable.","nullable":true},"metadata":{"type":"object","description":"The metadata of the document. You can add 20 total key-value pairs within these data limits:\n- key: 40 character limit. Square brackets ([ ]) can't be included in keys.\n- value: 300 character limit.","nullable":true,"additionalProperties":{"type":"string"}},"size_kb":{"type":"number","description":"The file size in kb.","nullable":true},"storage":{"type":"string","description":"The object storage ID to which the document is associated","nullable":false},"document_source_id":{"type":"string","description":"The document source ID this document belongs to","nullable":true},"is_externally_managed":{"type":"boolean","description":"Whether the document is externally managed (read-only in the UI)"}},"required":["id","file_name","external_id","original_file_name","original_file_path","original_author","extension","file_path","valid_from","valid_until","metadata","size_kb","storage","document_source_id","is_externally_managed"]}}},"paths":{"/v1/documents":{"get":{"operationId":"DocumentsController_listAll","parameters":[{"name":"after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"number"}},{"name":"externalId","required":false,"in":"query","schema":{"type":"string"}},{"name":"document_source_id","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedListWrapper"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DocumentDto"}}}}]}}}}}}}}}
```

## POST /v1/documents

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"CreateDocumentDto":{"type":"object","properties":{"file_name":{"type":"string","description":"A user friendly name for the document","nullable":false},"external_id":{"type":"string","description":"The id generated by the system from which the document was extracted"},"original_file_name":{"type":"string","description":"The file name as of the extracted file.","nullable":true},"original_file_path":{"type":"string","description":"The file path of the extracted file.","nullable":true},"original_author":{"type":"string","description":"The author of the document.","nullable":true},"extension":{"type":"string","description":"The file extension."},"file_path":{"type":"string","description":"The file path as stored in the object storage."},"valid_from":{"type":"string","description":"The date at which the document has been made available.","nullable":true},"valid_until":{"type":"string","description":"The date at which the document will be made unavailable.","nullable":true},"metadata":{"type":"object","description":"The metadata of the document. You can add 20 total key-value pairs within these data limits:\n- key: 40 character limit. Square brackets ([ ]) can't be included in keys.\n- value: 300 character limit.","nullable":true,"additionalProperties":{"type":"string"}},"size_kb":{"type":"number","description":"The file size in kb.","nullable":true},"storage":{"type":"string","description":"The object storage ID to which the document is associated","nullable":false},"document_source_id":{"type":"string","description":"The document source ID this document belongs to. Optional — when omitted, the document is attached to the org's default source.","nullable":true},"is_externally_managed":{"type":"boolean","description":"Whether the document is externally managed (read-only in the UI). Defaults to false.","nullable":true}},"required":["file_name","external_id","original_file_name","original_file_path","original_author","extension","file_path","valid_from","valid_until","metadata","size_kb","storage","document_source_id","is_externally_managed"]},"DocumentDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"file_name":{"type":"string","description":"A user friendly name for the document"},"external_id":{"type":"string","description":"The id generated by the system of referenced"},"original_file_name":{"type":"string","description":"The file name as of the extracted file.","nullable":true},"original_file_path":{"type":"string","description":"The file path of the extracted file.","nullable":true},"original_author":{"type":"string","description":"The author of the document.","nullable":true},"extension":{"type":"string","description":"The file extension."},"file_path":{"type":"string","description":"The file path as stored in the object storage."},"valid_from":{"type":"string","description":"The date at which the document has been made available.","nullable":true},"valid_until":{"type":"string","description":"The date at which the document will be made unavailable.","nullable":true},"metadata":{"type":"object","description":"The metadata of the document. You can add 20 total key-value pairs within these data limits:\n- key: 40 character limit. Square brackets ([ ]) can't be included in keys.\n- value: 300 character limit.","nullable":true,"additionalProperties":{"type":"string"}},"size_kb":{"type":"number","description":"The file size in kb.","nullable":true},"storage":{"type":"string","description":"The object storage ID to which the document is associated","nullable":false},"document_source_id":{"type":"string","description":"The document source ID this document belongs to","nullable":true},"is_externally_managed":{"type":"boolean","description":"Whether the document is externally managed (read-only in the UI)"}},"required":["id","file_name","external_id","original_file_name","original_file_path","original_author","extension","file_path","valid_from","valid_until","metadata","size_kb","storage","document_source_id","is_externally_managed"]}}},"paths":{"/v1/documents":{"post":{"operationId":"DocumentsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDocumentDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDto"}}}}}}}}}
```

## GET /v1/documents/{documentId}

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"DocumentDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"file_name":{"type":"string","description":"A user friendly name for the document"},"external_id":{"type":"string","description":"The id generated by the system of referenced"},"original_file_name":{"type":"string","description":"The file name as of the extracted file.","nullable":true},"original_file_path":{"type":"string","description":"The file path of the extracted file.","nullable":true},"original_author":{"type":"string","description":"The author of the document.","nullable":true},"extension":{"type":"string","description":"The file extension."},"file_path":{"type":"string","description":"The file path as stored in the object storage."},"valid_from":{"type":"string","description":"The date at which the document has been made available.","nullable":true},"valid_until":{"type":"string","description":"The date at which the document will be made unavailable.","nullable":true},"metadata":{"type":"object","description":"The metadata of the document. You can add 20 total key-value pairs within these data limits:\n- key: 40 character limit. Square brackets ([ ]) can't be included in keys.\n- value: 300 character limit.","nullable":true,"additionalProperties":{"type":"string"}},"size_kb":{"type":"number","description":"The file size in kb.","nullable":true},"storage":{"type":"string","description":"The object storage ID to which the document is associated","nullable":false},"document_source_id":{"type":"string","description":"The document source ID this document belongs to","nullable":true},"is_externally_managed":{"type":"boolean","description":"Whether the document is externally managed (read-only in the UI)"}},"required":["id","file_name","external_id","original_file_name","original_file_path","original_author","extension","file_path","valid_from","valid_until","metadata","size_kb","storage","document_source_id","is_externally_managed"]}}},"paths":{"/v1/documents/{documentId}":{"get":{"operationId":"DocumentsController_findOne","parameters":[{"name":"documentId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDto"}}}}}}}}}
```

## PUT /v1/documents/{documentId}

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"DocumentDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"file_name":{"type":"string","description":"A user friendly name for the document"},"external_id":{"type":"string","description":"The id generated by the system of referenced"},"original_file_name":{"type":"string","description":"The file name as of the extracted file.","nullable":true},"original_file_path":{"type":"string","description":"The file path of the extracted file.","nullable":true},"original_author":{"type":"string","description":"The author of the document.","nullable":true},"extension":{"type":"string","description":"The file extension."},"file_path":{"type":"string","description":"The file path as stored in the object storage."},"valid_from":{"type":"string","description":"The date at which the document has been made available.","nullable":true},"valid_until":{"type":"string","description":"The date at which the document will be made unavailable.","nullable":true},"metadata":{"type":"object","description":"The metadata of the document. You can add 20 total key-value pairs within these data limits:\n- key: 40 character limit. Square brackets ([ ]) can't be included in keys.\n- value: 300 character limit.","nullable":true,"additionalProperties":{"type":"string"}},"size_kb":{"type":"number","description":"The file size in kb.","nullable":true},"storage":{"type":"string","description":"The object storage ID to which the document is associated","nullable":false},"document_source_id":{"type":"string","description":"The document source ID this document belongs to","nullable":true},"is_externally_managed":{"type":"boolean","description":"Whether the document is externally managed (read-only in the UI)"}},"required":["id","file_name","external_id","original_file_name","original_file_path","original_author","extension","file_path","valid_from","valid_until","metadata","size_kb","storage","document_source_id","is_externally_managed"]}}},"paths":{"/v1/documents/{documentId}":{"put":{"operationId":"DocumentsController_update","parameters":[{"name":"documentId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDto"}}}}}}}}}
```

## DELETE /v1/documents/{documentId}

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"DocumentDeleteResultDto":{"type":"object","properties":{"id":{"type":"string"},"isDeleted":{"type":"boolean"}},"required":["id","isDeleted"]}}},"paths":{"/v1/documents/{documentId}":{"delete":{"operationId":"DocumentsController_delete","parameters":[{"name":"documentId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDeleteResultDto"}}}}}}}}}
```


# Object Storage

## GET /v1/object-storages

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"PaginatedListWrapper":{"type":"object","properties":{"paging":{"$ref":"#/components/schemas/PagingInfo"}},"required":["paging"]},"PagingInfo":{"type":"object","properties":{"next":{"$ref":"#/components/schemas/PagingNext"}},"required":["next"]},"PagingNext":{"type":"object","properties":{"after":{"type":"string"}},"required":["after"]},"ObjectStorageDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"name":{"type":"string","description":"The name of the object storage"}},"required":["id","name"]}}},"paths":{"/v1/object-storages":{"get":{"operationId":"DocumentsController_listAll","parameters":[{"name":"after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedListWrapper"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ObjectStorageDto"}}}}]}}}}}}}}}
```

## GET /v1/object-storages/{objectStorageId}

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"ObjectStorageDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"name":{"type":"string","description":"The name of the object storage"}},"required":["id","name"]}}},"paths":{"/v1/object-storages/{objectStorageId}":{"get":{"operationId":"DocumentsController_findOne","parameters":[{"name":"objectStorageId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectStorageDto"}}}}}}}}}
```

## POST /v1/object-storages/{objectStorageId}/upload

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"ObjectStorageUploadDTO":{"type":"object","properties":{"filePath":{"type":"string","description":"The path within the storage where the file has been stored"},"sizeKb":{"type":"number","description":"The stored file size in kb"},"storage":{"type":"string","description":"The Object Storage Id on which the file has been uploaded"}},"required":["filePath","sizeKb","storage"]}}},"paths":{"/v1/object-storages/{objectStorageId}/upload":{"post":{"operationId":"DocumentsController_upload","parameters":[{"name":"path","required":false,"in":"query","schema":{"type":"string"}},{"name":"objectStorageId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectStorageUploadDTO"}}}}}}}}}
```

## GET /v1/object-storages/{objectStorageId}/download

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}}},"paths":{"/v1/object-storages/{objectStorageId}/download":{"get":{"operationId":"DocumentsController_download","parameters":[{"name":"path","required":true,"in":"query","schema":{"type":"string"}},{"name":"objectStorageId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}}}}}}
```


# CDN

## HEAD /v1/cdn/{cdnId}/files/{fileName}

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}}},"paths":{"/v1/cdn/{cdnId}/files/{fileName}":{"head":{"operationId":"CdnController_headFile","parameters":[{"name":"cdnId","required":true,"in":"path","schema":{"type":"string"}},{"name":"fileName","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"File exists"},"404":{"description":"File or organization not found"}}}}}}
```

## PUT /v1/cdn/{cdnId}/files/{fileName}

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}}},"paths":{"/v1/cdn/{cdnId}/files/{fileName}":{"put":{"operationId":"CdnController_putFile","parameters":[{"name":"cdnId","required":true,"in":"path","schema":{"type":"string"}},{"name":"fileName","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"File uploaded successfully"},"404":{"description":"Organization not found"}}}}}}
```


# Objects

## GET /v1/objects

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"PaginatedListWrapper":{"type":"object","properties":{"paging":{"$ref":"#/components/schemas/PagingInfo"}},"required":["paging"]},"PagingInfo":{"type":"object","properties":{"next":{"$ref":"#/components/schemas/PagingNext"}},"required":["next"]},"PagingNext":{"type":"object","properties":{"after":{"type":"string"}},"required":["after"]},"ObjectDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"name":{"type":"string","description":"Name of the object"},"description":{"type":"string","description":"Description of the object","nullable":true}},"required":["id","name","description"]}}},"paths":{"/v1/objects":{"get":{"operationId":"ObjectsController_listAll","parameters":[{"name":"after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedListWrapper"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ObjectDto"}}}}]}}}}}}}}}
```

## GET /v1/objects/{objectId}

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"ObjectDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"name":{"type":"string","description":"Name of the object"},"description":{"type":"string","description":"Description of the object","nullable":true}},"required":["id","name","description"]}}},"paths":{"/v1/objects/{objectId}":{"get":{"operationId":"ObjectsController_findOne","parameters":[{"name":"objectId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectDto"}}}}}}}}}
```


# Object Events

## GET /v1/objects/{objectId}/events

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"PaginatedListWrapper":{"type":"object","properties":{"paging":{"$ref":"#/components/schemas/PagingInfo"}},"required":["paging"]},"PagingInfo":{"type":"object","properties":{"next":{"$ref":"#/components/schemas/PagingNext"}},"required":["next"]},"PagingNext":{"type":"object","properties":{"after":{"type":"string"}},"required":["after"]},"ObjectEventDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"name":{"type":"string","description":"Label of the event"},"description":{"type":"string","description":"Description of the event","nullable":true},"source":{"type":"string","description":"Source of the event","enum":["external","api","radar","calendar_model_sync","manual","system_recommendation"]},"object":{"type":"string","description":"Object ID representing the object of the event"},"record_id":{"type":"string","description":"ID of the record in the object"},"external_id":{"type":"string","description":"ID of the event in the external system (ex. CRM)","nullable":true},"sync_token":{"type":"string","description":"Token used to sync the event with external systems having an async create API","nullable":true},"event_type":{"type":"string","description":"Type of event (e.g., meeting, call, visit, holiday)","nullable":true},"start_at":{"type":"string","description":"Start date and time of the event (ISO 8601 format)"},"end_at":{"type":"string","description":"End date and time of the event (ISO 8601 format)"},"location_object":{"type":"string","description":"Encoded object ID for location","nullable":true},"location_record_id":{"type":"string","description":"Record ID in location object","nullable":true},"location_record_label":{"type":"string","description":"Human-readable location label","nullable":true},"review_status":{"type":"string","description":"Status of the review: pending, approved, or rejected","enum":["pending","approved","rejected"]},"recommendation_reason":{"type":"string","description":"Reason for system recommendation (only for system_recommendation source)","nullable":true},"planning_strategy":{"type":"string","description":"Planning strategy ID (only for system_recommendation source)","nullable":true},"calendar_model_sync_id":{"type":"string","description":"Calendar Model Sync ID that created this event","nullable":true},"radar_id":{"type":"string","description":"Radar ID that created this event","nullable":true},"updated_at":{"type":"string","description":"Last update timestamp (ISO 8601 format)","nullable":true}},"required":["id","name","description","source","object","record_id","external_id","sync_token","event_type","start_at","end_at","location_object","location_record_id","location_record_label","review_status","recommendation_reason","planning_strategy","calendar_model_sync_id","radar_id","updated_at"]}}},"paths":{"/v1/objects/{objectId}/events":{"get":{"operationId":"ObjectEventsController_listAll","parameters":[{"name":"after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"number"}},{"name":"record_id","required":false,"in":"query","schema":{"type":"string"}},{"name":"external_id","required":false,"in":"query","schema":{"type":"string"}},{"name":"sync_token","required":false,"in":"query","schema":{"type":"string"}},{"name":"source","required":false,"in":"query","schema":{"enum":["external","manual","system_recommendation"],"type":"string"}},{"name":"review_status","required":false,"in":"query","schema":{"enum":["pending","approved","rejected"],"type":"string"}},{"name":"event_type","required":false,"in":"query","schema":{"type":"string"}},{"name":"start_at_gte","required":false,"in":"query","description":"ISO 8601 format","schema":{"type":"string"}},{"name":"start_at_lte","required":false,"in":"query","description":"ISO 8601 format","schema":{"type":"string"}},{"name":"end_at_gte","required":false,"in":"query","description":"ISO 8601 format","schema":{"type":"string"}},{"name":"end_at_lte","required":false,"in":"query","description":"ISO 8601 format","schema":{"type":"string"}},{"name":"has_external_id","required":false,"in":"query","schema":{"type":"boolean"}},{"name":"calendar_model_sync_id","required":false,"in":"query","schema":{"type":"string"}},{"name":"radar_id","required":false,"in":"query","schema":{"type":"string"}},{"name":"updated_at_gte","required":false,"in":"query","description":"ISO 8601 format","schema":{"type":"string"}},{"name":"updated_at_lte","required":false,"in":"query","description":"ISO 8601 format","schema":{"type":"string"}},{"name":"objectId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedListWrapper"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ObjectEventDto"}}}}]}}}}}}}}}
```

## POST /v1/objects/{objectId}/events

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"CreateObjectEventDto":{"type":"object","properties":{"name":{"type":"string","description":"Label of the event"},"description":{"type":"string","description":"Description of the event","nullable":true},"source":{"type":"string","description":"Source of the event","enum":["external","api","radar","calendar_model_sync","manual","system_recommendation"]},"record_id":{"type":"string","description":"ID of the record in the object"},"external_id":{"type":"string","description":"ID of the event in the external system","nullable":true},"sync_token":{"type":"string","description":"Token used to sync the event with external systems (auto-generated UUID if not provided)","nullable":true},"event_type":{"type":"string","description":"Type of event (e.g., meeting, call, visit, holiday)","nullable":true},"start_at":{"type":"string","description":"Start date and time of the event (ISO 8601 format)"},"end_at":{"type":"string","description":"End date and time of the event (ISO 8601 format)"},"location_object":{"type":"string","description":"Object ID representing the location of the event","nullable":true},"location_record_id":{"type":"string","description":"Record ID in location object","nullable":true},"location_record_label":{"type":"string","description":"Human-readable location label","nullable":true},"review_status":{"type":"string","description":"Status of the review: pending, approved, or rejected (default: approved)","enum":["pending","approved","rejected"],"nullable":true},"recommendation_reason":{"type":"string","description":"Reason for system recommendation (only for system_recommendation source)","nullable":true},"planning_strategy":{"type":"string","description":"Encoded planning strategy ID","nullable":true},"calendar_model_sync_id":{"type":"string","description":"Calendar Model Sync ID to link this event to","nullable":true}},"required":["name","description","source","record_id","external_id","sync_token","event_type","start_at","end_at","location_object","location_record_id","location_record_label","review_status","recommendation_reason","planning_strategy","calendar_model_sync_id"]},"ObjectEventDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"name":{"type":"string","description":"Label of the event"},"description":{"type":"string","description":"Description of the event","nullable":true},"source":{"type":"string","description":"Source of the event","enum":["external","api","radar","calendar_model_sync","manual","system_recommendation"]},"object":{"type":"string","description":"Object ID representing the object of the event"},"record_id":{"type":"string","description":"ID of the record in the object"},"external_id":{"type":"string","description":"ID of the event in the external system (ex. CRM)","nullable":true},"sync_token":{"type":"string","description":"Token used to sync the event with external systems having an async create API","nullable":true},"event_type":{"type":"string","description":"Type of event (e.g., meeting, call, visit, holiday)","nullable":true},"start_at":{"type":"string","description":"Start date and time of the event (ISO 8601 format)"},"end_at":{"type":"string","description":"End date and time of the event (ISO 8601 format)"},"location_object":{"type":"string","description":"Encoded object ID for location","nullable":true},"location_record_id":{"type":"string","description":"Record ID in location object","nullable":true},"location_record_label":{"type":"string","description":"Human-readable location label","nullable":true},"review_status":{"type":"string","description":"Status of the review: pending, approved, or rejected","enum":["pending","approved","rejected"]},"recommendation_reason":{"type":"string","description":"Reason for system recommendation (only for system_recommendation source)","nullable":true},"planning_strategy":{"type":"string","description":"Planning strategy ID (only for system_recommendation source)","nullable":true},"calendar_model_sync_id":{"type":"string","description":"Calendar Model Sync ID that created this event","nullable":true},"radar_id":{"type":"string","description":"Radar ID that created this event","nullable":true},"updated_at":{"type":"string","description":"Last update timestamp (ISO 8601 format)","nullable":true}},"required":["id","name","description","source","object","record_id","external_id","sync_token","event_type","start_at","end_at","location_object","location_record_id","location_record_label","review_status","recommendation_reason","planning_strategy","calendar_model_sync_id","radar_id","updated_at"]}}},"paths":{"/v1/objects/{objectId}/events":{"post":{"operationId":"ObjectEventsController_create","parameters":[{"name":"objectId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateObjectEventDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectEventDto"}}}}}}}}}
```

## GET /v1/objects/{objectId}/events/{eventId}

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"ObjectEventDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"name":{"type":"string","description":"Label of the event"},"description":{"type":"string","description":"Description of the event","nullable":true},"source":{"type":"string","description":"Source of the event","enum":["external","api","radar","calendar_model_sync","manual","system_recommendation"]},"object":{"type":"string","description":"Object ID representing the object of the event"},"record_id":{"type":"string","description":"ID of the record in the object"},"external_id":{"type":"string","description":"ID of the event in the external system (ex. CRM)","nullable":true},"sync_token":{"type":"string","description":"Token used to sync the event with external systems having an async create API","nullable":true},"event_type":{"type":"string","description":"Type of event (e.g., meeting, call, visit, holiday)","nullable":true},"start_at":{"type":"string","description":"Start date and time of the event (ISO 8601 format)"},"end_at":{"type":"string","description":"End date and time of the event (ISO 8601 format)"},"location_object":{"type":"string","description":"Encoded object ID for location","nullable":true},"location_record_id":{"type":"string","description":"Record ID in location object","nullable":true},"location_record_label":{"type":"string","description":"Human-readable location label","nullable":true},"review_status":{"type":"string","description":"Status of the review: pending, approved, or rejected","enum":["pending","approved","rejected"]},"recommendation_reason":{"type":"string","description":"Reason for system recommendation (only for system_recommendation source)","nullable":true},"planning_strategy":{"type":"string","description":"Planning strategy ID (only for system_recommendation source)","nullable":true},"calendar_model_sync_id":{"type":"string","description":"Calendar Model Sync ID that created this event","nullable":true},"radar_id":{"type":"string","description":"Radar ID that created this event","nullable":true},"updated_at":{"type":"string","description":"Last update timestamp (ISO 8601 format)","nullable":true}},"required":["id","name","description","source","object","record_id","external_id","sync_token","event_type","start_at","end_at","location_object","location_record_id","location_record_label","review_status","recommendation_reason","planning_strategy","calendar_model_sync_id","radar_id","updated_at"]}}},"paths":{"/v1/objects/{objectId}/events/{eventId}":{"get":{"operationId":"ObjectEventsController_findOne","parameters":[{"name":"eventId","required":true,"in":"path","schema":{"type":"string"}},{"name":"objectId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectEventDto"}}}}}}}}}
```

## PUT /v1/objects/{objectId}/events/{eventId}

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"UpdateObjectEventDto":{"type":"object","properties":{"name":{"type":"string","description":"Label of the event","nullable":true},"description":{"type":"string","description":"Description of the event","nullable":true},"source":{"type":"string","description":"Source of the event","enum":["external","api","radar","calendar_model_sync","manual","system_recommendation"],"nullable":true},"external_id":{"type":"string","description":"ID of the event in the external system","nullable":true},"sync_token":{"type":"string","description":"Token used to sync the event with external systems","nullable":true},"event_type":{"type":"string","description":"Type of event (e.g., meeting, call, visit, holiday)","nullable":true},"start_at":{"type":"string","description":"Start date and time of the event (ISO 8601 format)","nullable":true},"end_at":{"type":"string","description":"End date and time of the event (ISO 8601 format)","nullable":true},"location_object":{"type":"string","description":"Object ID for location","nullable":true},"location_record_id":{"type":"string","description":"Record ID in location object","nullable":true},"location_record_label":{"type":"string","description":"Human-readable location label","nullable":true},"review_status":{"type":"string","description":"Status of the review: pending, approved, or rejected","enum":["pending","approved","rejected"],"nullable":true},"recommendation_reason":{"type":"string","description":"Reason for system recommendation (only for system_recommendation source)","nullable":true},"planning_strategy":{"type":"string","description":"Planning strategy ID (only for system_recommendation source)","nullable":true}},"required":["name","description","source","external_id","sync_token","event_type","start_at","end_at","location_object","location_record_id","location_record_label","review_status","recommendation_reason","planning_strategy"]},"ObjectEventDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"name":{"type":"string","description":"Label of the event"},"description":{"type":"string","description":"Description of the event","nullable":true},"source":{"type":"string","description":"Source of the event","enum":["external","api","radar","calendar_model_sync","manual","system_recommendation"]},"object":{"type":"string","description":"Object ID representing the object of the event"},"record_id":{"type":"string","description":"ID of the record in the object"},"external_id":{"type":"string","description":"ID of the event in the external system (ex. CRM)","nullable":true},"sync_token":{"type":"string","description":"Token used to sync the event with external systems having an async create API","nullable":true},"event_type":{"type":"string","description":"Type of event (e.g., meeting, call, visit, holiday)","nullable":true},"start_at":{"type":"string","description":"Start date and time of the event (ISO 8601 format)"},"end_at":{"type":"string","description":"End date and time of the event (ISO 8601 format)"},"location_object":{"type":"string","description":"Encoded object ID for location","nullable":true},"location_record_id":{"type":"string","description":"Record ID in location object","nullable":true},"location_record_label":{"type":"string","description":"Human-readable location label","nullable":true},"review_status":{"type":"string","description":"Status of the review: pending, approved, or rejected","enum":["pending","approved","rejected"]},"recommendation_reason":{"type":"string","description":"Reason for system recommendation (only for system_recommendation source)","nullable":true},"planning_strategy":{"type":"string","description":"Planning strategy ID (only for system_recommendation source)","nullable":true},"calendar_model_sync_id":{"type":"string","description":"Calendar Model Sync ID that created this event","nullable":true},"radar_id":{"type":"string","description":"Radar ID that created this event","nullable":true},"updated_at":{"type":"string","description":"Last update timestamp (ISO 8601 format)","nullable":true}},"required":["id","name","description","source","object","record_id","external_id","sync_token","event_type","start_at","end_at","location_object","location_record_id","location_record_label","review_status","recommendation_reason","planning_strategy","calendar_model_sync_id","radar_id","updated_at"]}}},"paths":{"/v1/objects/{objectId}/events/{eventId}":{"put":{"operationId":"ObjectEventsController_update","parameters":[{"name":"eventId","required":true,"in":"path","schema":{"type":"string"}},{"name":"objectId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateObjectEventDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectEventDto"}}}}}}}}}
```

## DELETE /v1/objects/{objectId}/events/{eventId}

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"ObjectEventDeleteResultDto":{"type":"object","properties":{"id":{"type":"string"},"isDeleted":{"type":"boolean"}},"required":["id","isDeleted"]}}},"paths":{"/v1/objects/{objectId}/events/{eventId}":{"delete":{"operationId":"ObjectEventsController_delete","parameters":[{"name":"eventId","required":true,"in":"path","schema":{"type":"string"}},{"name":"objectId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObjectEventDeleteResultDto"}}}}}}}}}
```