{
"openapi": "3.1.1",
"info": {
"title": "NiftyImages.API | v1",
"version": "1.0.0"
},
"servers": [
{
"url": "https://dev.niftyimages.com/"
}
],
"paths": {
"/v2/whoami": {
"get": {
"tags": [
"WhoAmIEndpoint"
],
"summary": "Return the identity associated with the caller's API key.",
"operationId": "WhoAmI",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WhoAmIResponse"
}
}
}
}
}
}
},
"/v2/image-types": {
"get": {
"tags": [
"Images"
],
"summary": "List the valid values accepted by GET /v2/images?type=.",
"operationId": "ListImageTypes",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImageTypesList"
}
}
}
}
}
}
},
"/v2/image-thumbnails/{token}/{imageId}": {
"get": {
"tags": [
"Images"
],
"summary": "Serve a short-lived image thumbnail URL minted by an image list or detail response.",
"operationId": "GetImageThumbnail",
"parameters": [
{
"name": "token",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "imageId",
"in": "path",
"required": true,
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"404": {
"description": "Not Found"
}
}
}
},
"/v2/timer-frame-previews/{token}/{conversationId}/{timerFrameId}": {
"get": {
"tags": [
"Timer Frames"
],
"summary": "Render a short-lived temporary TimerFrame draft preview GIF.",
"operationId": "GetTimerFramePreview",
"parameters": [
{
"name": "token",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "conversationId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "timerFrameId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"404": {
"description": "Not Found"
}
}
}
},
"/v2/images": {
"get": {
"tags": [
"Images"
],
"summary": "List the authenticated account's images.",
"operationId": "ListImages",
"parameters": [
{
"name": "limit",
"in": "query",
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"format": "int32"
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "type",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "status",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "q",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CursorPageOfImageSummary"
}
}
}
}
}
}
},
"/v2/images/{id}": {
"get": {
"tags": [
"Images"
],
"summary": "Get a single image, including its rendered URL.",
"operationId": "GetImage",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImageDetail"
}
}
}
},
"404": {
"description": "Not Found"
}
}
},
"delete": {
"tags": [
"Images"
],
"summary": "Soft-delete an image (sets Active=false). Idempotent.",
"operationId": "DeleteImage",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"404": {
"description": "Not Found"
}
}
},
"patch": {
"tags": [
"Images"
],
"summary": "Rename an image. Only the 'name' field is editable here.",
"operationId": "RenameImage",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": "integer",
"format": "int32"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RenameImageRequest"
}
}
},
"required": true
},
"responses": {
"204": {
"description": "No Content"
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/images/{id}/restore": {
"post": {
"tags": [
"Images"
],
"summary": "Restore a soft-deleted image back to the root folder. Idempotent.",
"operationId": "RestoreImage",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"404": {
"description": "Not Found"
}
}
}
},
"/v2/images/lookup": {
"post": {
"tags": [
"Images"
],
"summary": "Find an image by its production URL. Returns the same shape as GET /v2/images/{id}.",
"operationId": "LookupImageByUrl",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LookupImageByUrlRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImageDetail"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/maps/{mapId}": {
"get": {
"tags": [
"Maps"
],
"summary": "Get a single map's metadata and location counts.",
"operationId": "GetMap",
"parameters": [
{
"name": "mapId",
"in": "path",
"required": true,
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MapResponse"
}
}
}
},
"404": {
"description": "Not Found"
}
}
},
"patch": {
"tags": [
"Maps"
],
"summary": "Update a map's name, search radius, or max results. Only supplied fields are applied.",
"operationId": "UpdateMap",
"parameters": [
{
"name": "mapId",
"in": "path",
"required": true,
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": "integer",
"format": "int32"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateMapRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MapResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/maps/{mapId}/locations": {
"get": {
"tags": [
"Maps"
],
"summary": "Search locations within a map. Supply one filter at a time: ?address=, ?uniqueId=, or ?lat=&lng=(&radiusMiles=).",
"operationId": "SearchLocations",
"parameters": [
{
"name": "mapId",
"in": "path",
"required": true,
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": "integer",
"format": "int32"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"format": "int32"
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "address",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "uniqueId",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "lat",
"in": "query",
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
"type": [
"number",
"string"
],
"format": "double"
}
},
{
"name": "lng",
"in": "query",
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
"type": [
"number",
"string"
],
"format": "double"
}
},
{
"name": "radiusMiles",
"in": "query",
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CursorPageOfLocationResponse"
}
}
}
},
"404": {
"description": "Not Found"
}
}
},
"post": {
"tags": [
"Maps"
],
"summary": "Add a location. Body may supply an address (queued for geocoding) or raw lat/lng.",
"operationId": "AddLocation",
"parameters": [
{
"name": "mapId",
"in": "path",
"required": true,
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": "integer",
"format": "int32"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddLocationRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LocationResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/maps/{mapId}/locations/{locationId}": {
"get": {
"tags": [
"Maps"
],
"summary": "Get a single location.",
"operationId": "GetLocation",
"parameters": [
{
"name": "mapId",
"in": "path",
"required": true,
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": "integer",
"format": "int32"
}
},
{
"name": "locationId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LocationResponse"
}
}
}
},
"404": {
"description": "Not Found"
}
}
},
"patch": {
"tags": [
"Maps"
],
"summary": "Update any field of a location. Changing address re-queues geocoding.",
"operationId": "UpdateLocation",
"parameters": [
{
"name": "mapId",
"in": "path",
"required": true,
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": "integer",
"format": "int32"
}
},
{
"name": "locationId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateLocationRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LocationResponse"
}
}
}
},
"404": {
"description": "Not Found"
}
}
},
"delete": {
"tags": [
"Maps"
],
"summary": "Hard-delete a location. Idempotent (204 whether or not the location existed).",
"operationId": "DeleteLocation",
"parameters": [
{
"name": "mapId",
"in": "path",
"required": true,
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": "integer",
"format": "int32"
}
},
{
"name": "locationId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"404": {
"description": "Not Found"
}
}
}
},
"/v2/stores": {
"get": {
"tags": [
"Stores"
],
"summary": "List the caller's stores.",
"operationId": "ListStores",
"parameters": [
{
"name": "limit",
"in": "query",
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"format": "int32"
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "q",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CursorPageOfStoreSummary"
}
}
}
}
}
},
"post": {
"tags": [
"Stores"
],
"summary": "Create a new store. Server generates the id and tags store_type with the API key that created it.",
"operationId": "CreateStore",
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/CreateStoreRequest"
}
]
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreDetail"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/stores/access": {
"get": {
"tags": [
"Stores"
],
"summary": "Return the store access granted to the caller's API key.",
"operationId": "GetStoreAccess",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreAccessResponse"
}
}
}
},
"404": {
"description": "Not Found"
}
}
}
},
"/v2/stores/{storeId}": {
"get": {
"tags": [
"Stores"
],
"summary": "Get a store's metadata and schema (properties).",
"operationId": "GetStore",
"parameters": [
{
"name": "storeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreDetail"
}
}
}
},
"404": {
"description": "Not Found"
}
}
},
"patch": {
"tags": [
"Stores"
],
"summary": "Update a store's name, description, or recordTtl. Only supplied fields are applied.",
"operationId": "UpdateStore",
"parameters": [
{
"name": "storeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/UpdateStoreRequest"
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreDetail"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
},
"delete": {
"tags": [
"Stores"
],
"summary": "Soft-delete a store (flips Status to DELETED). Records stay in storage until a background cleanup runs.",
"operationId": "DeleteStore",
"parameters": [
{
"name": "storeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteStoreResponse"
}
}
}
},
"404": {
"description": "Not Found"
}
}
}
},
"/v2/stores/{storeId}/properties": {
"post": {
"tags": [
"Stores"
],
"summary": "Add a property to a store's schema.",
"operationId": "AddStoreProperty",
"parameters": [
{
"name": "storeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/StorePropertyRequest"
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreDetail"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/stores/{storeId}/properties/{propertyName}": {
"patch": {
"tags": [
"Stores"
],
"summary": "Edit non-structural fields of a property. type, unique, and name are immutable — add a new property and migrate if you need those changed.",
"operationId": "UpdateStoreProperty",
"parameters": [
{
"name": "storeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "propertyName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/UpdatePropertyRequest"
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreDetail"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
},
"delete": {
"tags": [
"Stores"
],
"summary": "Remove a property from a store's schema. Rejected if the property is unique (removing it would orphan existing record ids).",
"operationId": "DeleteStoreProperty",
"parameters": [
{
"name": "storeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "propertyName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreDetail"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/stores/{storeId}/records": {
"get": {
"tags": [
"Stores"
],
"summary": "List records in a store, newest first. Cursor-paged.",
"operationId": "ListStoreRecords",
"parameters": [
{
"name": "storeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"format": "int32"
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "sortBy",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "sortDir",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CursorPageOfStoreRecordResponse"
}
}
}
},
"404": {
"description": "Not Found"
}
}
},
"post": {
"tags": [
"Stores"
],
"summary": "Add a record. Body is a dynamic JSON object whose keys match the store's property names.",
"operationId": "AddStoreRecord",
"parameters": [
{
"name": "storeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/JsonObject"
}
]
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreRecordResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/stores/{storeId}/records/{recordId}": {
"get": {
"tags": [
"Stores"
],
"summary": "Get a single record by its id.",
"operationId": "GetStoreRecord",
"parameters": [
{
"name": "storeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "recordId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreRecordResponse"
}
}
}
},
"404": {
"description": "Not Found"
}
}
},
"delete": {
"tags": [
"Stores"
],
"summary": "Delete a record by its id. Idempotent (200 whether or not the record existed).",
"operationId": "DeleteStoreRecord",
"parameters": [
{
"name": "storeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "recordId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteRecordResponse"
}
}
}
},
"404": {
"description": "Not Found"
}
}
},
"patch": {
"tags": [
"Stores"
],
"summary": "Partially update a record (JSON Merge Patch, RFC 7396). Send only the fields to change; null unsets.",
"operationId": "PatchStoreRecord",
"parameters": [
{
"name": "storeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "recordId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/JsonObject"
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreRecordResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/stores/{storeId}/records/batch": {
"post": {
"tags": [
"Stores"
],
"summary": "Upsert up to 100 records in one call. Each record is attempted independently; per-record status is returned in the response.",
"operationId": "BatchUpsertStoreRecords",
"parameters": [
{
"name": "storeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/BatchUpsertRecordsRequest"
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchUpsertRecordsResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/stores/{storeId}/records/delete-by-key": {
"post": {
"tags": [
"Stores"
],
"summary": "Delete a record by unique-property values. Body supplies the unique fields; the server computes the id the same way record creation does.",
"operationId": "DeleteStoreRecordByKey",
"parameters": [
{
"name": "storeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/JsonObject"
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteRecordResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/stores/{storeId}/records/lookup": {
"post": {
"tags": [
"Stores"
],
"summary": "Find a record by its unique-property values. Same id rule as delete-by-key.",
"operationId": "LookupStoreRecord",
"parameters": [
{
"name": "storeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/JsonObject"
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreRecordResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/stores/{storeId}/records/validate": {
"post": {
"tags": [
"Stores"
],
"summary": "Dry-run: run a candidate record through schema validation and return what would be stored, without writing to the store.",
"operationId": "ValidateStoreRecord",
"parameters": [
{
"name": "storeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/JsonObject"
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreRecordResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/stores/{storeId}/records/search": {
"post": {
"tags": [
"Stores"
],
"summary": "Filter + sort records. Body accepts an array of field/op/value filters joined by AND or OR. Max 100 hits; use narrower filters for larger result sets.",
"operationId": "SearchStoreRecords",
"parameters": [
{
"name": "storeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/SearchRecordsRequest"
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRecordsResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/stores/{storeId}/records/count": {
"post": {
"tags": [
"Stores"
],
"summary": "Count records matching the supplied filters (or the entire store when filters are omitted).",
"operationId": "CountStoreRecords",
"parameters": [
{
"name": "storeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/CountRecordsRequest"
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CountRecordsResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/stores/{storeId}/records/aggregate": {
"post": {
"tags": [
"Stores"
],
"summary": "Run sum/avg/min/max over a number-typed property, optionally filtered. Returns null when no records match.",
"operationId": "AggregateStoreRecords",
"parameters": [
{
"name": "storeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/AggregateRecordsRequest"
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AggregateRecordsResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/stores/{storeId}/records/batch-delete": {
"post": {
"tags": [
"Stores"
],
"summary": "Delete up to 100 records by id in one call. Idempotent per record (unknown ids count as already-deleted).",
"operationId": "BatchDeleteStoreRecords",
"parameters": [
{
"name": "storeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/BatchDeleteRecordsRequest"
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchDeleteRecordsResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/stores/{storeId}/records/export": {
"get": {
"tags": [
"Stores"
],
"summary": "Export up to 10,000 records as JSON or CSV. Narrow with /records/search for larger datasets.",
"operationId": "ExportStoreRecords",
"parameters": [
{
"name": "storeId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "format",
"in": "query",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/v2/fonts": {
"get": {
"tags": [
"Fonts"
],
"summary": "List fonts available to the authenticated account.",
"operationId": "ListFonts",
"parameters": [
{
"name": "scope",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FontSummary"
}
}
}
}
}
}
},
"post": {
"tags": [
"Fonts"
],
"summary": "Upload a custom font file. The font is rendered once before it is saved.",
"operationId": "UploadFont",
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/IFormFile"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FontSummary"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/fonts/from-url": {
"post": {
"tags": [
"Fonts"
],
"summary": "Add a custom font from a URL. The font is rendered once before it is saved.",
"operationId": "AddFontFromUrl",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddFontRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FontSummary"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/fonts/{id}": {
"delete": {
"tags": [
"Fonts"
],
"summary": "Delete a custom font owned by the authenticated account.",
"operationId": "DeleteFont",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"404": {
"description": "Not Found"
}
}
}
},
"/v2/timer-frames": {
"post": {
"tags": [
"Timer Frames"
],
"summary": "Create a temporary TimerFrame draft for an agent conversation.",
"operationId": "CreateTimerFrame",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateTimerFrameRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TimerFrameResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/timer-frames/{timerFrameId}": {
"get": {
"tags": [
"Timer Frames"
],
"summary": "Get a temporary TimerFrame draft.",
"operationId": "GetTimerFrame",
"parameters": [
{
"name": "timerFrameId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "conversationId",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TimerFrameResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
},
"patch": {
"tags": [
"Timer Frames"
],
"summary": "Apply structured changes to a temporary TimerFrame draft.",
"operationId": "UpdateTimerFrame",
"parameters": [
{
"name": "timerFrameId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateTimerFrameRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TimerFrameResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
},
"delete": {
"tags": [
"Timer Frames"
],
"summary": "Delete a temporary TimerFrame draft.",
"operationId": "DeleteTimerFrame",
"parameters": [
{
"name": "timerFrameId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "conversationId",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/timer-frames/{timerFrameId}/save": {
"post": {
"tags": [
"Timer Frames"
],
"summary": "Save a temporary TimerFrame draft as a timer image.",
"operationId": "SaveTimerFrame",
"parameters": [
{
"name": "timerFrameId",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SaveTimerFrameRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SavedTimerFrameResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
},
"/v2/timers/{id}/target-date": {
"patch": {
"tags": [
"Timers"
],
"summary": "Update a canvas timer's target date.",
"operationId": "UpdateTimerTargetDate",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": "integer",
"format": "int32"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "null"
},
{
"$ref": "#/components/schemas/UpdateTimerTargetDateRequest"
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TimerTargetDateResponse"
}
}
}
},
"404": {
"description": "Not Found"
},
"400": {
"description": "Bad Request",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/HttpValidationProblemDetails"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"AddFontRequest": {
"required": [
"url"
],
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "HTTP or HTTPS URL for the font file to add."
},
"name": {
"type": [
"null",
"string"
],
"description": "Optional display name for the font. When omitted, the API uses the URL filename."
}
},
"description": "Adds a custom font from a public URL."
},
"AddLocationRequest": {
"required": [
"address",
"latitude",
"longitude",
"uniqueId",
"properties"
],
"type": "object",
"properties": {
"address": {
"type": [
"null",
"string"
],
"description": "Free-form address to geocode."
},
"latitude": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
"type": [
"null",
"number",
"string"
],
"description": "Latitude, when coordinates are known client-side.",
"format": "double"
},
"longitude": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
"type": [
"null",
"number",
"string"
],
"description": "Longitude, when coordinates are known client-side.",
"format": "double"
},
"uniqueId": {
"type": [
"null",
"string"
],
"description": "Optional caller-supplied identifier (must be unique within the map)."
},
"properties": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
},
"description": "Optional custom properties, positional against the map's field mapping."
}
},
"description": "Body for POST /v2/maps/{mapId}/locations.\nSupply either Address (queued for geocoding) or\nLatitude + Longitude (used as-is)."
},
"AggregateRecordsRequest": {
"required": [
"field",
"op",
"filters",
"match"
],
"type": "object",
"properties": {
"field": {
"type": [
"null",
"string"
],
"description": "Schema property name. Must be a number-typed property."
},
"op": {
"type": [
"null",
"string"
],
"description": "Aggregation operator: `sum`, `avg`, `min`, or `max`."
},
"filters": {
"type": [
"null",
"array"
],
"items": {
"$ref": "#/components/schemas/RecordFilter"
},
"description": "Zero or more filters to narrow the input set."
},
"match": {
"type": [
"null",
"string"
],
"description": "How to combine filters: `all` (AND, default) or `any` (OR)."
}
},
"description": "Body for POST /v2/stores/{storeId}/records/aggregate. Runs one of\n`sum, avg, min, max` over a number-typed schema property, optionally\nfiltered via the same filter vocabulary as /records/search."
},
"AggregateRecordsResponse": {
"required": [
"storeId",
"storeName",
"field",
"op",
"value"
],
"type": "object",
"properties": {
"storeId": {
"type": "string",
"description": "Parent store identifier."
},
"storeName": {
"type": [
"null",
"string"
],
"description": "Parent store display name."
},
"field": {
"type": "string",
"description": "Echo of the field that was aggregated."
},
"op": {
"type": "string",
"description": "Echo of the operator that was applied."
},
"value": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
"type": [
"null",
"number",
"string"
],
"description": "Aggregated value. Null when the partition was empty.",
"format": "double"
}
},
"description": "Response for /records/aggregate."
},
"BatchDeleteRecordResult": {
"required": [
"index",
"id",
"status",
"error"
],
"type": "object",
"properties": {
"index": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Position of the id in the request body's `ids` array (0-based).",
"format": "int32"
},
"id": {
"type": "string",
"description": "The id the caller asked to delete."
},
"status": {
"type": "string",
"description": "`deleted` (record was removed or was already gone) or `failed`."
},
"error": {
"type": [
"null",
"string"
],
"description": "Error message when Status is `failed`."
}
},
"description": "One record's outcome in a batch delete."
},
"BatchDeleteRecordsRequest": {
"required": [
"ids"
],
"type": "object",
"properties": {
"ids": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
},
"description": "Record ids to delete. Unknown ids are treated as already-deleted (success)."
}
},
"description": "Body for POST /v2/stores/{storeId}/records/batch-delete. Symmetric with\n/records/batch. Max 100 ids per call; delete-by-filter is intentionally\nnot supported (too easy to drop the wrong rows)."
},
"BatchDeleteRecordsResponse": {
"required": [
"storeId",
"storeName",
"processed",
"succeeded",
"failed",
"results"
],
"type": "object",
"properties": {
"storeId": {
"type": "string"
},
"storeName": {
"type": [
"null",
"string"
]
},
"processed": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"format": "int32"
},
"succeeded": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"format": "int32"
},
"failed": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"format": "int32"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BatchDeleteRecordResult"
}
}
},
"description": "Response for /records/batch-delete. Per-record status mirrors the batch\nupsert response so agents can reuse the same inspection pattern for both."
},
"BatchUpsertRecordResult": {
"required": [
"index",
"id",
"status",
"error"
],
"type": "object",
"properties": {
"index": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Position of the record in the request body's `records` array (0-based).",
"format": "int32"
},
"id": {
"type": [
"null",
"string"
],
"description": "Id of the record that was upserted. Null when the record failed validation before an id could be computed."
},
"status": {
"type": "string",
"description": "`upserted` — record was written to the store.\n`invalid` — record failed schema validation (e.g. missing required property).\n`failed` — record passed validation but the underlying write threw."
},
"error": {
"type": [
"null",
"string"
],
"description": "Error message when Status is `invalid` or `failed`; null otherwise."
}
},
"description": "One record's outcome in a batch upsert."
},
"BatchUpsertRecordsRequest": {
"required": [
"records"
],
"type": "object",
"properties": {
"records": {
"type": [
"null",
"array"
],
"items": {
"$ref": "#/components/schemas/JsonObject"
},
"description": "Records to upsert. Maximum 100 per request."
}
},
"description": "Body for POST /v2/stores/{storeId}/records/batch. Each entry in\nRecords is a dynamic JSON object matching the store's\nschema (same shape as POST /records)."
},
"BatchUpsertRecordsResponse": {
"required": [
"storeId",
"storeName",
"processed",
"succeeded",
"failed",
"results"
],
"type": "object",
"properties": {
"storeId": {
"type": "string",
"description": "Parent store identifier."
},
"storeName": {
"type": [
"null",
"string"
],
"description": "Parent store display name."
},
"processed": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Count of records the server attempted.",
"format": "int32"
},
"succeeded": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Count of records successfully upserted.",
"format": "int32"
},
"failed": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Count of records that failed validation or the Cosmos write.",
"format": "int32"
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BatchUpsertRecordResult"
},
"description": "Per-record outcome. `Results[i]` corresponds to the i-th record in the request body."
}
},
"description": "Response for POST /v2/stores/{storeId}/records/batch. Always returns 200\nwhen the request parsed — per-record status lives in Results.\nAgents should inspect Failed and Results\nto decide whether to retry individual rows."
},
"CountRecordsRequest": {
"required": [
"filters",
"match"
],
"type": "object",
"properties": {
"filters": {
"type": [
"null",
"array"
],
"items": {
"$ref": "#/components/schemas/RecordFilter"
},
"description": "Zero or more field/op/value triples. Empty/null means count everything."
},
"match": {
"type": [
"null",
"string"
],
"description": "How to combine filters: `all` (AND, default) or `any` (OR)."
}
},
"description": "Body for POST /v2/stores/{storeId}/records/count. Same filter vocabulary\nas /records/search — omit the filters for a total count of the store."
},
"CountRecordsResponse": {
"required": [
"storeId",
"storeName",
"count"
],
"type": "object",
"properties": {
"storeId": {
"type": "string",
"description": "Parent store identifier."
},
"storeName": {
"type": [
"null",
"string"
],
"description": "Parent store display name."
},
"count": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Number of records matching the filter.",
"format": "int64"
}
},
"description": "Response for /records/count."
},
"CreateStoreRequest": {
"required": [
"name",
"description",
"recordTtl",
"properties"
],
"type": "object",
"properties": {
"name": {
"type": [
"null",
"string"
],
"description": "Human-readable store name. Required."
},
"description": {
"type": [
"null",
"string"
],
"description": "Optional free-form description."
},
"recordTtl": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"null",
"integer",
"string"
],
"description": "Default TTL for new records, in seconds. Defaults to 2,592,000 (30 days) if omitted. Use -1 for forever. Studio stores days internally; the API converts.",
"format": "int32"
},
"properties": {
"type": [
"null",
"array"
],
"items": {
"$ref": "#/components/schemas/StorePropertyRequest"
},
"description": "Schema properties (at least one). Each carries name + type + optional required/unique/description/defaults."
}
},
"description": "Body for POST /v2/stores. The server generates the id, sets\n`store_type = \"API : {apiKeyId}\"`, resolves the owner's email, and\nstamps `createdUtc`. At least one property is required (the domain\nwon't persist an empty-schema store)."
},
"CreateTimerFrameRequest": {
"type": "object",
"properties": {
"conversationId": {
"type": [
"null",
"string"
],
"description": "Client-supplied conversation/session id. If omitted, the API generates one."
},
"targetDateUtc": {
"type": [
"null",
"string"
],
"description": "Countdown target in UTC. Defaults to seven days from now when omitted.",
"format": "date-time"
},
"timeZoneId": {
"type": [
"null",
"string"
],
"description": "Optional Windows or Olson time zone id used for saved timer metadata."
},
"frame": {
"description": "Optional full TimerFrame JSON. When omitted, the API creates a basic countdown frame."
},
"width": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"null",
"integer",
"string"
],
"description": "Optional canvas width for generated frames.",
"format": "int32"
},
"height": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"null",
"integer",
"string"
],
"description": "Optional canvas height for generated frames.",
"format": "int32"
},
"backgroundColor": {
"type": [
"null",
"string"
],
"description": "Optional solid frame background color."
},
"backgroundImageId": {
"type": [
"null",
"string"
],
"description": "Optional existing Shared.FileAccess image id to use as the frame background."
},
"backgroundImageUrl": {
"type": [
"null",
"string"
],
"description": "Optional HTTPS image URL. The API downloads and uploads it to Shared.FileAccess before storing the resulting image id on the timer frame."
},
"backgroundImageDataUri": {
"type": [
"null",
"string"
],
"description": "Optional data:image/...;base64,... payload. The API uploads it to Shared.FileAccess before storing the resulting image id on the timer frame."
},
"numberColor": {
"type": [
"null",
"string"
],
"description": "Optional number text color."
},
"labelColor": {
"type": [
"null",
"string"
],
"description": "Optional label text color when labels are shown."
},
"numberFontId": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"null",
"integer",
"string"
],
"description": "Optional font id to use for generated timer text.",
"format": "int32"
},
"numberFontSize": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"null",
"integer",
"string"
],
"description": "Optional number font size.",
"format": "int32"
},
"usePieCharts": {
"type": [
"null",
"boolean"
],
"description": "Whether generated frames should put pie progress behind each number."
},
"showLabels": {
"type": [
"null",
"boolean"
],
"description": "Whether generated frames should show labels under the numbers."
},
"useTicks": {
"type": [
"null",
"boolean"
],
"description": "Alias for segmented/tick-circle progress behind each number."
},
"useSegmentedCircles": {
"type": [
"null",
"boolean"
],
"description": "Alias for segmented/tick-circle progress behind each number."
},
"numberBackplate": {
"type": [
"null",
"string"
],
"description": "Optional explicit backplate style: none, ring, circle, pie, ticks, segmented."
},
"backplateColor": {
"type": [
"null",
"string"
],
"description": "Optional progress/fill color for number backplates."
},
"backplateTrackColor": {
"type": [
"null",
"string"
],
"description": "Optional track/background color for number backplates."
},
"startOver": {
"type": "boolean",
"description": "When true, deletes the current frame for the conversation before creating this one.",
"default": false
}
},
"description": "Creates a temporary timer draft for an agent conversation."
},
"CursorPageOfImageSummary": {
"required": [
"data",
"nextCursor"
],
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ImageSummary"
},
"description": "The items on this page, in the order the endpoint defines."
},
"nextCursor": {
"type": [
"null",
"string"
],
"description": "Opaque cursor to pass back as `?cursor=` to fetch the next page. `null` means this is the last page. Filters (type, status, q) are NOT encoded in the cursor — re-supply them when paging."
}
},
"description": "Cursor-paginated list envelope."
},
"CursorPageOfLocationResponse": {
"required": [
"data",
"nextCursor"
],
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/LocationResponse"
},
"description": "The items on this page, in the order the endpoint defines."
},
"nextCursor": {
"type": [
"null",
"string"
],
"description": "Opaque cursor to pass back as `?cursor=` to fetch the next page. `null` means this is the last page. Filters (type, status, q) are NOT encoded in the cursor — re-supply them when paging."
}
},
"description": "Cursor-paginated list envelope."
},
"CursorPageOfStoreRecordResponse": {
"required": [
"data",
"nextCursor"
],
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StoreRecordResponse"
},
"description": "The items on this page, in the order the endpoint defines."
},
"nextCursor": {
"type": [
"null",
"string"
],
"description": "Opaque cursor to pass back as `?cursor=` to fetch the next page. `null` means this is the last page. Filters (type, status, q) are NOT encoded in the cursor — re-supply them when paging."
}
},
"description": "Cursor-paginated list envelope."
},
"CursorPageOfStoreSummary": {
"required": [
"data",
"nextCursor"
],
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StoreSummary"
},
"description": "The items on this page, in the order the endpoint defines."
},
"nextCursor": {
"type": [
"null",
"string"
],
"description": "Opaque cursor to pass back as `?cursor=` to fetch the next page. `null` means this is the last page. Filters (type, status, q) are NOT encoded in the cursor — re-supply them when paging."
}
},
"description": "Cursor-paginated list envelope."
},
"DeleteRecordResponse": {
"required": [
"id",
"storeId",
"storeName"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the record that was targeted (may not have existed — delete is idempotent)."
},
"storeId": {
"type": "string",
"description": "Parent store identifier."
},
"storeName": {
"type": [
"null",
"string"
],
"description": "Parent store display name."
}
},
"description": "Response for the delete-record endpoints. Echoes the store context so\nagents can confirm which store was touched without re-fetching."
},
"DeleteStoreResponse": {
"required": [
"id",
"name"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Store identifier that was marked DELETED."
},
"name": {
"type": [
"null",
"string"
],
"description": "Store display name at the time of deletion."
}
},
"description": "Response for DELETE /v2/stores/{id}. Echoes the store's id + name so agents\ncan confirm which store was soft-deleted. The store's records stay in\nstorage until a background cleanup process removes them, so an accidental\ndelete is recoverable by support flipping Status back to ACTIVE."
},
"FontSummary": {
"required": [
"id",
"name",
"scope",
"createdUtc"
],
"type": "object",
"properties": {
"id": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Numeric identifier for the font.",
"format": "int32"
},
"name": {
"type": "string",
"description": "Display name for the font."
},
"scope": {
"type": "string",
"description": "Font scope. Values are `public` or `user`."
},
"createdUtc": {
"type": [
"null",
"string"
],
"description": "When the font was created, in UTC. Public fonts may not have this populated.",
"format": "date-time"
}
},
"description": "Summary shape for a font available to the authenticated account."
},
"HttpValidationProblemDetails": {
"type": "object",
"properties": {
"type": {
"type": [
"null",
"string"
]
},
"title": {
"type": [
"null",
"string"
]
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"null",
"integer",
"string"
],
"format": "int32"
},
"detail": {
"type": [
"null",
"string"
]
},
"instance": {
"type": [
"null",
"string"
]
},
"errors": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"IFormFile": {
"type": "string",
"format": "binary"
},
"ImageDetail": {
"required": [
"id",
"name",
"imageType",
"opens",
"createdUtc",
"updatedUtc",
"active",
"url",
"thumbnailUrl"
],
"type": "object",
"properties": {
"id": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Numeric identifier for the image. Unique per account.",
"format": "int32"
},
"name": {
"type": [
"null",
"string"
],
"description": "User-supplied display name. May be null or empty if never set."
},
"imageType": {
"type": "string",
"description": "Concrete image type (e.g. `basic`, `countdown`, `canvas_timer`). See `GET /v2/image-types` for the full list."
},
"opens": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Total number of times the image has been rendered (tracked opens).",
"format": "int32"
},
"createdUtc": {
"type": "string",
"description": "When the image was first created, in UTC.",
"format": "date-time"
},
"updatedUtc": {
"type": "string",
"description": "When the image was most recently modified, in UTC.",
"format": "date-time"
},
"active": {
"type": "boolean",
"description": "`true` when the image is live; `false` when soft-deleted. Toggle via `DELETE` and `POST /restore`."
},
"url": {
"type": [
"null",
"string"
],
"description": "Fully-qualified URL that renders the image. `null` when `Active` is `false`."
},
"thumbnailUrl": {
"type": [
"null",
"string"
],
"description": "Short-lived URL for a small thumbnail suitable for browsing/listing. `null` when unavailable, such as for soft-deleted images."
}
},
"description": " Detail shape returned by `GET /v2/images/{id}`. Extends\n ImageSummary's fields with the rendered image URL.\n When Active is false the image has been soft-deleted\nand Url is null — the image will not serve content."
},
"ImageSummary": {
"required": [
"id",
"name",
"imageType",
"opens",
"createdUtc",
"updatedUtc",
"active",
"thumbnailUrl"
],
"type": "object",
"properties": {
"id": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Numeric identifier for the image. Unique per account.",
"format": "int32"
},
"name": {
"type": [
"null",
"string"
],
"description": "User-supplied display name. May be null or empty if never set."
},
"imageType": {
"type": "string",
"description": "Concrete image type (e.g. `basic`, `countdown`, `canvas_timer`). See `GET /v2/image-types`."
},
"opens": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Total number of times the image has been rendered (tracked opens).",
"format": "int32"
},
"createdUtc": {
"type": "string",
"description": "When the image was first created, in UTC.",
"format": "date-time"
},
"updatedUtc": {
"type": "string",
"description": "When the image was most recently modified, in UTC.",
"format": "date-time"
},
"active": {
"type": "boolean",
"description": "`true` when the image is live; `false` when soft-deleted."
},
"thumbnailUrl": {
"type": [
"null",
"string"
],
"description": "Short-lived URL for a small thumbnail suitable for browsing/listing. `null` when unavailable, such as for soft-deleted images."
}
},
"description": "Summary shape returned by list endpoints. The full image detail\n(including rendered URL) is served by `GET /v2/images/{id}`."
},
"ImageTypesList": {
"required": [
"data"
],
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "string"
},
"description": "The canonical image-type identifiers (e.g. `basic`, `countdown`, `canvas_timer`, `classic_timer`, `personalized`)."
}
},
"description": "Response shape for `GET /v2/image-types`. Lists the valid\n`imageType` values accepted by list/filter endpoints."
},
"JsonElement": { },
"JsonObject": {
"type": "object"
},
"LocationResponse": {
"required": [
"id",
"uniqueId",
"status",
"latitude",
"longitude",
"searchAddress",
"formattedAddress",
"address",
"city",
"state",
"zip",
"country",
"county",
"neighborhood",
"properties"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable location identifier within the map."
},
"uniqueId": {
"type": [
"null",
"string"
],
"description": "Caller-supplied unique identifier (e.g. store number), if any."
},
"status": {
"type": "string",
"description": "Geocoding status: notProcessed, ok, notFound, providedByUser."
},
"latitude": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
"type": [
"number",
"string"
],
"description": "Latitude (0 if not yet geocoded).",
"format": "double"
},
"longitude": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
"type": [
"number",
"string"
],
"description": "Longitude (0 if not yet geocoded).",
"format": "double"
},
"searchAddress": {
"type": [
"null",
"string"
],
"description": "Address supplied by the caller used to query Google."
},
"formattedAddress": {
"type": [
"null",
"string"
],
"description": "Address as returned by Google; null until geocoding succeeds."
},
"address": {
"type": [
"null",
"string"
],
"description": "Street line of the formatted address."
},
"city": {
"type": [
"null",
"string"
],
"description": "City component."
},
"state": {
"type": [
"null",
"string"
],
"description": "State/region component."
},
"zip": {
"type": [
"null",
"string"
],
"description": "Postal code component."
},
"country": {
"type": [
"null",
"string"
],
"description": "Country component."
},
"county": {
"type": [
"null",
"string"
],
"description": "County component."
},
"neighborhood": {
"type": [
"null",
"string"
],
"description": "Neighborhood component."
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Custom properties, positional against the map's field mapping."
}
},
"description": "A single location belonging to a map."
},
"LookupImageByUrlRequest": {
"required": [
"url"
],
"type": "object",
"properties": {
"url": {
"type": [
"null",
"string"
],
"description": "A NiftyImages image URL — full URL (https://img1.niftyimages.com/...), path-only,\nor bare segment form. Any querystring (merge-tag params) is ignored."
}
},
"description": "Body for POST /v2/images/lookup. Convenience for clients who have a\nproduction image URL and want to find the matching image without\nknowing its numeric id."
},
"MapResponse": {
"required": [
"id",
"name",
"searchRadiusMiles",
"maxResults",
"locationsGood",
"locationsNotGood",
"locationsNotProcessed"
],
"type": "object",
"properties": {
"id": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Map identifier (same int id returned by /v2/images?type=map).",
"format": "int32"
},
"name": {
"type": [
"null",
"string"
],
"description": "Display name."
},
"searchRadiusMiles": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Radius used by proximity searches on this map.",
"format": "int32"
},
"maxResults": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Cap on the number of locations returned by a proximity search.",
"format": "int32"
},
"locationsGood": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Count of successfully geocoded locations.",
"format": "int32"
},
"locationsNotGood": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Count of locations whose address could not be geocoded.",
"format": "int32"
},
"locationsNotProcessed": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Count of locations still waiting for geocoding.",
"format": "int32"
}
},
"description": "Metadata for a single map."
},
"RecordFilter": {
"required": [
"field",
"op",
"value"
],
"type": "object",
"properties": {
"field": {
"type": [
"null",
"string"
],
"description": "Schema property name."
},
"op": {
"type": [
"null",
"string"
],
"description": "Comparison operator (see summary for the supported set per type)."
},
"value": {
"type": [
"null",
"string"
],
"description": "Value to compare against. Ignored by `empty` / `notEmpty`."
}
},
"description": " A single filter condition. string? RecordFilter.Field names a schema property,\n string? RecordFilter.Op picks the comparison, string? RecordFilter.Value is the compare-to.\n\n Supported ops depend on the property's type:\n * string/url: eq, ne, contains, startsWith, endsWith, empty, notEmpty\n* number: eq, ne, gt, gte, lt, lte\n* boolean: eq (value must be true or false)\n* datetime: on, before, after (value is an ISO 8601 date)"
},
"RenameImageRequest": {
"required": [
"name"
],
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The new display name. Required; trimmed and capped at 50 characters server-side."
}
},
"description": "Request body for `PATCH /v2/images/{id}`. Only the display name is\neditable through this endpoint."
},
"SavedTimerFrameResponse": {
"required": [
"id",
"name",
"imageType",
"timerFrameId",
"conversationId"
],
"type": "object",
"properties": {
"id": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Saved image id.",
"format": "int32"
},
"name": {
"type": "string",
"description": "Saved image name."
},
"imageType": {
"type": "string",
"description": "Saved image type."
},
"timerFrameId": {
"type": "string",
"description": "Draft id that was saved."
},
"conversationId": {
"type": "string",
"description": "Conversation/session id that owned the draft."
}
},
"description": "Result returned after saving a TimerFrame draft as a committed timer image."
},
"SaveTimerFrameRequest": {
"required": [
"conversationId",
"name"
],
"type": "object",
"properties": {
"conversationId": {
"type": "string",
"description": "Conversation/session id that owns the draft."
},
"name": {
"type": "string",
"description": "Name for the saved timer image."
}
},
"description": "Saves a temporary timer draft as a timer image."
},
"SearchRecordsRequest": {
"required": [
"filters",
"match",
"sortBy",
"sortDir",
"limit"
],
"type": "object",
"properties": {
"filters": {
"type": [
"null",
"array"
],
"items": {
"$ref": "#/components/schemas/RecordFilter"
},
"description": "Zero or more field/op/value triples. Empty list means \"match all records\"."
},
"match": {
"type": [
"null",
"string"
],
"description": "How to combine filters: `all` (AND, default) or `any` (OR)."
},
"sortBy": {
"type": [
"null",
"string"
],
"description": "Schema property name to sort by. `date_created` or null sorts by creation time."
},
"sortDir": {
"type": [
"null",
"string"
],
"description": "Sort direction: `asc` or `desc`. Defaults to desc."
},
"limit": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"null",
"integer",
"string"
],
"description": "Max records to return. Clamped server-side (default 25, max 100).",
"format": "int32"
}
},
"description": "Body for POST /v2/stores/{storeId}/records/search.\nShared with /records/count and /records/aggregate — filter + match semantics\nare identical across the three so agents learn one filter vocabulary."
},
"SearchRecordsResponse": {
"required": [
"storeId",
"storeName",
"count",
"records"
],
"type": "object",
"properties": {
"storeId": {
"type": "string",
"description": "Parent store identifier."
},
"storeName": {
"type": [
"null",
"string"
],
"description": "Parent store display name."
},
"count": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Number of records returned. Never greater than the requested limit.",
"format": "int32"
},
"records": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StoreRecordResponse"
},
"description": "Matching records, in the order the sort produced them."
}
},
"description": "Response for /v2/stores/{storeId}/records/search. Flat array — no cursor\npagination in v1 (search caps at 100 hits; narrow filters for larger\ndatasets). A future version may switch to CursorPage if needed."
},
"StoreAccessResponse": {
"required": [
"apiKeyId",
"scope",
"storeId",
"storeName",
"recordTtl",
"properties"
],
"type": "object",
"properties": {
"apiKeyId": {
"type": [
"null",
"string"
],
"description": "Caller API key identifier."
},
"scope": {
"type": "string",
"description": "account or store."
},
"storeId": {
"type": [
"null",
"string"
],
"description": "Assigned store when scope is store."
},
"storeName": {
"type": [
"null",
"string"
],
"description": "Assigned store name when scope is store."
},
"recordTtl": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"null",
"integer",
"string"
],
"description": "Default record TTL in seconds (-1 forever). Null when account-scoped. Studio UI shows days (30 days → 2592000).",
"format": "int32"
},
"properties": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StorePropertyResponse"
},
"description": "Schema properties for the assigned store."
}
},
"description": "Describes the store access granted to the caller's API key.\nAccount-scoped keys can access all stores owned by the account; store-scoped\nkeys can access exactly one store."
},
"StoreDetail": {
"required": [
"id",
"name",
"description",
"recordCount",
"recordTtl",
"createdUtc",
"properties"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Store identifier."
},
"name": {
"type": [
"null",
"string"
],
"description": "Display name."
},
"description": {
"type": [
"null",
"string"
],
"description": "Optional description set by the owner."
},
"recordCount": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Live count of records currently in the store. Computed on read (one Cosmos COUNT per call).",
"format": "int32"
},
"recordTtl": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Default TTL for new records, in seconds (Studio UI shows days; e.g. 30 days → 2592000). -1 means forever.",
"format": "int32"
},
"createdUtc": {
"type": [
"null",
"string"
],
"description": "When the store was created, in UTC. Null for stores that pre-date the creation-timestamp field.",
"format": "date-time"
},
"properties": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StorePropertyResponse"
},
"description": "Ordered list of schema properties (fields). Unique-flagged properties feed the generated record id."
}
},
"description": "Full store metadata + schema, returned by GET /v2/stores/{storeId}.\nInternal concerns (saved queries, api_keys, csv_imports, custom_properties)\nare intentionally excluded from the v2 surface."
},
"StorePropertyRequest": {
"required": [
"name",
"type",
"required",
"unique",
"description",
"defaultValue",
"dateInputFormat",
"dateInputTimezone"
],
"type": "object",
"properties": {
"name": {
"type": [
"null",
"string"
],
"description": "Property name. Required. Must be unique within the store."
},
"type": {
"type": [
"null",
"string"
],
"description": "One of: `string`, `number`, `boolean`, `datetime`, `url_image`, `url_link`."
},
"required": {
"type": [
"null",
"boolean"
],
"description": "When true, records missing this property fail validation on write."
},
"unique": {
"type": [
"null",
"boolean"
],
"description": "When true, this property feeds the record-id rule (concatenated + lowercased with any other unique properties, sorted by name)."
},
"description": {
"type": [
"null",
"string"
],
"description": "Optional human-readable description."
},
"defaultValue": {
"type": [
"null",
"string"
],
"description": "Optional default value applied when records omit this field."
},
"dateInputFormat": {
"type": [
"null",
"string"
],
"description": "For datetime properties: format of incoming values (`ISO 8601`, `epoch`, `epochmilliseconds`, or a custom format string). Ignored for non-datetime types."
},
"dateInputTimezone": {
"type": [
"null",
"string"
],
"description": "For datetime properties: source timezone (e.g. `UTC`, `America/Los_Angeles`). Ignored for non-datetime types."
}
},
"description": "Body shape for creating or adding a property. Shared between\nPOST /v2/stores and POST /v2/stores/{id}/properties."
},
"StorePropertyResponse": {
"required": [
"name",
"type",
"required",
"unique",
"description",
"defaultValue",
"dateInputFormat",
"dateInputTimezone"
],
"type": "object",
"properties": {
"name": {
"type": [
"null",
"string"
],
"description": "Property name, used as the JSON key when reading and writing records."
},
"type": {
"type": "string",
"description": "One of: string, number, boolean, datetime, url_image, url_link."
},
"required": {
"type": "boolean",
"description": "True if this property must be supplied when adding a record."
},
"unique": {
"type": "boolean",
"description": "True if this property feeds the generated record id. Multiple unique properties are concatenated (lowercased, ordered by name)."
},
"description": {
"type": [
"null",
"string"
],
"description": "Optional human-readable description."
},
"defaultValue": {
"type": [
"null",
"string"
],
"description": "Optional default applied when the caller omits the field."
},
"dateInputFormat": {
"type": [
"null",
"string"
],
"description": "For datetime properties: expected input format (e.g. iso8601, epoch, epochmilliseconds, or a custom format string)."
},
"dateInputTimezone": {
"type": [
"null",
"string"
],
"description": "For datetime properties: source timezone of incoming values."
}
},
"description": "One schema property (field) on a store."
},
"StoreRecordResponse": {
"required": [
"id",
"storeId",
"storeName",
"createdUtc",
"model"
],
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
],
"description": "Record identifier. Deterministic for stores that define unique properties (lowercased concat of unique values, ordered by property name); otherwise a GUID."
},
"storeId": {
"type": "string",
"description": "Parent store identifier."
},
"storeName": {
"type": [
"null",
"string"
],
"description": "Parent store display name. Echoed on every record response so agents can refer to the store without an extra round-trip."
},
"createdUtc": {
"type": "string",
"description": "When the record was created, in UTC.",
"format": "date-time"
},
"model": {
"oneOf": [
{
"type": "null"
},
{
"description": "Field values keyed by property name.",
"$ref": "#/components/schemas/JsonObject"
}
]
}
},
"description": "One record returned by any /v2/stores/{storeId}/records endpoint.\nModel carries the record's field values as a dynamic JSON\nobject, shaped by the store's schema."
},
"StoreSummary": {
"required": [
"id",
"name",
"description",
"recordCount",
"recordTtl",
"createdUtc"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Store identifier. Use this in all /v2/stores/{storeId}/... paths."
},
"name": {
"type": [
"null",
"string"
],
"description": "Display name."
},
"description": {
"type": [
"null",
"string"
],
"description": "Optional description set by the owner."
},
"recordCount": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Approximate count of records currently in the store.",
"format": "int32"
},
"recordTtl": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Default TTL for new records, in seconds (Studio UI shows days; e.g. 30 days → 2592000). -1 means forever.",
"format": "int32"
},
"createdUtc": {
"type": [
"null",
"string"
],
"description": "When the store was created, in UTC. Null for stores that pre-date the creation-timestamp field.",
"format": "date-time"
}
},
"description": "Summary row in GET /v2/stores."
},
"TimerFramePreview": {
"required": [
"url",
"contentType",
"width",
"height"
],
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Preview GIF URL."
},
"contentType": {
"type": "string",
"description": "Preview content type."
},
"width": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Preview width.",
"format": "int32"
},
"height": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Preview height.",
"format": "int32"
}
},
"description": "Short-lived animated preview metadata for a TimerFrame draft."
},
"TimerFrameResponse": {
"required": [
"timerFrameId",
"conversationId",
"expiresUtc",
"targetDateUtc",
"timeZoneId",
"frameCount",
"preview",
"frame",
"saveReady",
"appliedChanges",
"validationWarnings"
],
"type": "object",
"properties": {
"timerFrameId": {
"type": "string",
"description": "Temporary draft id."
},
"conversationId": {
"type": "string",
"description": "Conversation/session id that owns the draft."
},
"expiresUtc": {
"type": "string",
"description": "When the temporary draft expires.",
"format": "date-time"
},
"targetDateUtc": {
"type": "string",
"description": "Countdown target in UTC.",
"format": "date-time"
},
"timeZoneId": {
"type": "string",
"description": "Time zone id used for saved timer metadata."
},
"frameCount": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Number of GIF frames used for animated preview rendering.",
"format": "int32"
},
"preview": {
"description": "Authenticated animated preview URL and metadata.",
"$ref": "#/components/schemas/TimerFramePreview"
},
"frame": {
"description": "Normalized TimerFrame JSON.",
"$ref": "#/components/schemas/JsonElement"
},
"saveReady": {
"type": "boolean",
"description": "Whether the current draft validated and rendered successfully."
},
"appliedChanges": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable changes applied by this request."
},
"validationWarnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Non-fatal notes about requested changes."
}
},
"description": "Temporary timer draft state returned after every create/update."
},
"TimerTargetDateResponse": {
"required": [
"id",
"imageType",
"targetDateUtc",
"timeZoneId",
"localTargetDate",
"localTargetTime"
],
"type": "object",
"properties": {
"id": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"integer",
"string"
],
"description": "Numeric image/deployment id of the updated timer.",
"format": "int32"
},
"imageType": {
"type": "string",
"description": "Timer image type."
},
"targetDateUtc": {
"type": "string",
"description": "Normalized target date stored by the API, in UTC.",
"format": "date-time"
},
"timeZoneId": {
"type": "string",
"description": "Time zone used for interpreting or displaying the target date."
},
"localTargetDate": {
"type": "string",
"description": "Target date rendered in TimeZoneId, formatted as `MM/dd/yyyy`."
},
"localTargetTime": {
"type": "string",
"description": "Target time rendered in TimeZoneId, formatted as `hh:mm tt`."
}
},
"description": "Response returned after a timer target date update."
},
"UpdateLocationRequest": {
"required": [
"address",
"latitude",
"longitude",
"uniqueId",
"properties"
],
"type": "object",
"properties": {
"address": {
"type": [
"null",
"string"
]
},
"latitude": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
"type": [
"null",
"number",
"string"
],
"format": "double"
},
"longitude": {
"pattern": "^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$",
"type": [
"null",
"number",
"string"
],
"format": "double"
},
"uniqueId": {
"type": [
"null",
"string"
]
},
"properties": {
"type": [
"null",
"array"
],
"items": {
"type": "string"
}
}
},
"description": "Body for PATCH /v2/maps/{mapId}/locations/{locationId}. Any field may be omitted;\nonly supplied fields are applied. Changing Address without also\nsupplying lat/lng re-queues the location for geocoding."
},
"UpdateMapRequest": {
"required": [
"name",
"searchRadiusMiles",
"maxResults"
],
"type": "object",
"properties": {
"name": {
"type": [
"null",
"string"
],
"description": "Display name for the map. Must be non-empty when supplied."
},
"searchRadiusMiles": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"null",
"integer",
"string"
],
"description": "Radius used by proximity searches. Zero or greater.",
"format": "int32"
},
"maxResults": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"null",
"integer",
"string"
],
"description": "Cap on the number of locations returned by a proximity search. Zero or greater.",
"format": "int32"
}
},
"description": "Body for PATCH /v2/maps/{mapId}. Any field may be omitted; only supplied\nfields are applied."
},
"UpdatePropertyRequest": {
"required": [
"required",
"description",
"defaultValue",
"dateInputFormat",
"dateInputTimezone"
],
"type": "object",
"properties": {
"required": {
"type": [
"null",
"boolean"
],
"description": "Toggle whether this property is required on future writes."
},
"description": {
"type": [
"null",
"string"
],
"description": "New human-readable description."
},
"defaultValue": {
"type": [
"null",
"string"
],
"description": "New default value when the field is absent on write."
},
"dateInputFormat": {
"type": [
"null",
"string"
],
"description": "Datetime properties only: new input-format hint."
},
"dateInputTimezone": {
"type": [
"null",
"string"
],
"description": "Datetime properties only: new input timezone."
}
},
"description": "Body for PATCH /v2/stores/{id}/properties/{name}. Only non-structural fields\nare editable — type, unique, and name stay frozen so existing records don't\nsilently reinterpret."
},
"UpdateStoreRequest": {
"required": [
"name",
"description",
"recordTtl"
],
"type": "object",
"properties": {
"name": {
"type": [
"null",
"string"
],
"description": "New display name. Must be non-empty if supplied."
},
"description": {
"type": [
"null",
"string"
],
"description": "New description. Pass an empty string to clear."
},
"recordTtl": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"null",
"integer",
"string"
],
"description": "New default record TTL in seconds. Existing records keep their own TTL; only new writes pick up the change.",
"format": "int32"
}
},
"description": "Body for PATCH /v2/stores/{id}. Only the supplied fields are applied;\nomitted fields are preserved. Name must be non-empty if supplied."
},
"UpdateTimerFrameRequest": {
"required": [
"conversationId"
],
"type": "object",
"properties": {
"conversationId": {
"type": "string",
"description": "Conversation/session id that owns the draft."
},
"targetDateUtc": {
"type": [
"null",
"string"
],
"description": "Optional new countdown target in UTC.",
"format": "date-time"
},
"timeZoneId": {
"type": [
"null",
"string"
],
"description": "Optional Windows or Olson time zone id used for saved timer metadata."
},
"frame": {
"description": "Optional full TimerFrame JSON replacement."
},
"width": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"null",
"integer",
"string"
],
"description": "Optional new canvas width.",
"format": "int32"
},
"height": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"null",
"integer",
"string"
],
"description": "Optional new canvas height.",
"format": "int32"
},
"backgroundColor": {
"type": [
"null",
"string"
],
"description": "Optional solid frame background color."
},
"backgroundImageId": {
"type": [
"null",
"string"
],
"description": "Optional existing Shared.FileAccess image id to use as the frame background. Pass an empty string to remove an image background."
},
"backgroundImageUrl": {
"type": [
"null",
"string"
],
"description": "Optional HTTPS image URL. The API downloads and uploads it to Shared.FileAccess before storing the resulting image id on the timer frame."
},
"backgroundImageDataUri": {
"type": [
"null",
"string"
],
"description": "Optional data:image/...;base64,... payload. The API uploads it to Shared.FileAccess before storing the resulting image id on the timer frame."
},
"numberColor": {
"type": [
"null",
"string"
],
"description": "Optional number text color."
},
"labelColor": {
"type": [
"null",
"string"
],
"description": "Optional label text color."
},
"numberFontId": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"null",
"integer",
"string"
],
"description": "Optional font id to use for generated timer text.",
"format": "int32"
},
"numberFontSize": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"null",
"integer",
"string"
],
"description": "Optional absolute number font size.",
"format": "int32"
},
"numberFontSizeDelta": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"type": [
"null",
"integer",
"string"
],
"description": "Optional relative number font size adjustment.",
"format": "int32"
},
"usePieCharts": {
"type": [
"null",
"boolean"
],
"description": "Whether generated frames should put pie progress behind each number."
},
"showLabels": {
"type": [
"null",
"boolean"
],
"description": "Whether generated frames should show labels under the numbers."
},
"useTicks": {
"type": [
"null",
"boolean"
],
"description": "Alias for segmented/tick-circle progress behind each number."
},
"useSegmentedCircles": {
"type": [
"null",
"boolean"
],
"description": "Alias for segmented/tick-circle progress behind each number."
},
"numberBackplate": {
"type": [
"null",
"string"
],
"description": "Optional explicit backplate style: none, ring, circle, pie, ticks, segmented."
},
"backplateColor": {
"type": [
"null",
"string"
],
"description": "Optional progress/fill color for number backplates."
},
"backplateTrackColor": {
"type": [
"null",
"string"
],
"description": "Optional track/background color for number backplates."
}
},
"description": "Applies structured changes to a temporary timer draft."
},
"UpdateTimerTargetDateRequest": {
"required": [
"targetDate",
"timeZoneId"
],
"type": "object",
"properties": {
"targetDate": {
"type": [
"null",
"string"
],
"description": "Required target date. Accepts an absolute ISO 8601 value with `Z` or an offset, or a local date/time\nsuch as `7/4/2026 12:00am`. Date-only values default to midnight."
},
"timeZoneId": {
"type": [
"null",
"string"
],
"description": "Optional Windows or Olson time zone id. When omitted and TargetDate has no offset,\nthe timer's existing time zone is used."
}
},
"description": "Body for `PATCH /v2/timers/{id}/target-date`. Updates only the timer target date."
},
"WhoAmIResponse": {
"required": [
"email",
"apiKeyID",
"name"
],
"type": "object",
"properties": {
"email": {
"type": [
"null",
"string"
],
"description": "The email address of the account that owns the API key."
},
"apiKeyID": {
"type": [
"null",
"string"
],
"description": "The identifier of the API key used for this request."
},
"name": {
"type": [
"null",
"string"
],
"description": "Friendly name of the API key (set when the key was created)."
}
},
"description": "Response shape for `GET /v2/whoami`. Identifies the account and\nAPI key associated with the caller's bearer token."
}
},
"securitySchemes": {
"Bearer": {
"type": "http",
"description": "Send your NiftyImages API key as `Authorization: Bearer {apiKey}`.",
"scheme": "bearer"
}
}
},
"security": [
{
"Bearer": [ ]
}
],
"tags": [
{
"name": "WhoAmIEndpoint"
},
{
"name": "Images"
},
{
"name": "Timer Frames"
},
{
"name": "Maps"
},
{
"name": "Stores"
},
{
"name": "Fonts"
},
{
"name": "Timers"
}
]
}