{ "openapi": "3.0.0", "info": { "title": "HairDora API", "version": "1.0.0" }, "servers": [ { "url": "https://api.hairdora.com" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "basic", "description": "HTTP Basic auth carrying only the API key secret: Authorization: Basic base64()." }, "accessToken": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Operator session token issued by the HairDora dashboard: Authorization: Token ." } } }, "paths": { "/api/appointments": { "get": { "tags": [ "Appointments" ], "summary": "List appointments", "description": "Lists the appointments of your organization. Requires the `appointments:read` scope. Optionally filter by `salonId`, `clientId` and a `startTime`/`endTime` window.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "query", "name": "salonId", "schema": { "type": "string" } }, { "in": "query", "name": "clientId", "schema": { "type": "string" } }, { "in": "query", "name": "startTime", "schema": { "type": "string" } }, { "in": "query", "name": "endTime", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "skip", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "sortField", "schema": { "type": "string", "example": "startTime" } }, { "in": "query", "name": "sortDirection", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } }, { "in": "query", "name": "fields", "description": "Comma-separated projection of fields to return", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of appointments", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "clientId": { "type": "string", "minLength": 1 }, "startTime": { "type": "string", "format": "date-time" }, "endTime": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "services": { "type": "array", "items": { "type": "object" } }, "reminders": { "type": "array", "items": { "type": "object" } }, "lastEditTime": { "type": "string", "format": "date-time" } } } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "403": { "description": "API key is missing the `appointments:read` scope", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "429": { "description": "API key rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "getApiAppointments" }, "post": { "tags": [ "Appointments" ], "summary": "Create an appointment", "description": "Creates an appointment. Requires the `appointments:write` scope. Fires the `appointment.created` webhook.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "The created appointment", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "clientId": { "type": "string", "minLength": 1 }, "startTime": { "type": "string", "format": "date-time" }, "endTime": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "services": { "type": "array", "items": { "type": "object" } }, "reminders": { "type": "array", "items": { "type": "object" } }, "lastEditTime": { "type": "string", "format": "date-time" } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "postApiAppointments" } }, "/api/appointments/{appointmentId}": { "get": { "tags": [ "Appointments" ], "summary": "Get an appointment", "description": "Returns a single appointment by id. Appointments belonging to another organization respond 404. Requires the `appointments:read` scope.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "appointmentId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The appointment", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "clientId": { "type": "string", "minLength": 1 }, "startTime": { "type": "string", "format": "date-time" }, "endTime": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "services": { "type": "array", "items": { "type": "object" } }, "reminders": { "type": "array", "items": { "type": "object" } }, "lastEditTime": { "type": "string", "format": "date-time" } } } } } }, "404": { "description": "Not found (or owned by another organization)", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "getApiAppointmentsAppointmentId" }, "put": { "tags": [ "Appointments" ], "summary": "Update an appointment", "description": "Updates an appointment. Requires the `appointments:write` scope. Appointments owned by another organization respond 404. Fires the `appointment.updated` webhook.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "appointmentId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The updated appointment", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "clientId": { "type": "string", "minLength": 1 }, "startTime": { "type": "string", "format": "date-time" }, "endTime": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "services": { "type": "array", "items": { "type": "object" } }, "reminders": { "type": "array", "items": { "type": "object" } }, "lastEditTime": { "type": "string", "format": "date-time" } } } } } }, "404": { "description": "Not found (or owned by another organization)", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "putApiAppointmentsAppointmentId", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "clientId": { "type": "string", "minLength": 1 }, "startTime": { "type": "string", "format": "date-time" }, "endTime": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "services": { "type": "array", "items": { "type": "object" } }, "reminders": { "type": "array", "items": { "type": "object" } }, "lastEditTime": { "type": "string", "format": "date-time" } } } } } } }, "delete": { "tags": [ "Appointments" ], "summary": "Delete an appointment", "description": "Deletes an appointment by id. Requires the `appointments:write` scope. Appointments owned by another organization respond 404. Fires the `appointment.deleted` webhook.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "appointmentId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The deleted appointment id", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "clientId": { "type": "string", "minLength": 1 }, "startTime": { "type": "string", "format": "date-time" }, "endTime": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "services": { "type": "array", "items": { "type": "object" } }, "reminders": { "type": "array", "items": { "type": "object" } }, "lastEditTime": { "type": "string", "format": "date-time" } } } } } }, "404": { "description": "Not found (or owned by another organization)", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "deleteApiAppointmentsAppointmentId" } }, "/api/clients": { "get": { "tags": [ "Clients" ], "summary": "List clients", "description": "Lists the clients of your organization. Requires the `clients:read` scope. Optionally filter by `salonId`, `_id`, `_ids`, `email` or `userId`, and bound the result with `limit`/`skip`.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "query", "name": "salonId", "schema": { "type": "string" } }, { "in": "query", "name": "email", "schema": { "type": "string" } }, { "in": "query", "name": "fields", "description": "Comma-separated projection of fields to return", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "skip", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Array of clients", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "language": { "type": "string" }, "lastEditTime": { "type": "string", "format": "date-time" } } } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "403": { "description": "API key is missing the `clients:read` scope", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "429": { "description": "API key rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "getApiClients" }, "post": { "tags": [ "Clients" ], "summary": "Create a client", "description": "Creates a client. Requires the `clients:write` scope. Fires the `client.created` webhook.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "The created client", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "language": { "type": "string" }, "lastEditTime": { "type": "string", "format": "date-time" } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "postApiClients" } }, "/api/clients/{clientId}": { "get": { "tags": [ "Clients" ], "summary": "Get a client", "description": "Returns a single client by id. Clients belonging to another organization respond 404. Requires the `clients:read` scope.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "clientId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The client", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "language": { "type": "string" }, "lastEditTime": { "type": "string", "format": "date-time" } } } } } }, "404": { "description": "Not found (or owned by another organization)", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "getApiClientsClientId" }, "put": { "tags": [ "Clients" ], "summary": "Update a client", "description": "Updates a client. Requires the `clients:write` scope. Clients owned by another organization respond 404. Fires the `client.updated` webhook.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "clientId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The updated client", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "language": { "type": "string" }, "lastEditTime": { "type": "string", "format": "date-time" } } } } } }, "404": { "description": "Not found (or owned by another organization)", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "putApiClientsClientId", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "language": { "type": "string" }, "lastEditTime": { "type": "string", "format": "date-time" } } } } } } }, "delete": { "tags": [ "Clients" ], "summary": "Delete a client", "description": "Deletes a client by id. Requires the `clients:write` scope. Clients owned by another organization respond 404.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "clientId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The deleted client id", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "language": { "type": "string" }, "lastEditTime": { "type": "string", "format": "date-time" } } } } } }, "404": { "description": "Not found (or owned by another organization)", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "deleteApiClientsClientId" } }, "/api/keys": { "get": { "tags": [ "Keys" ], "summary": "List API keys", "description": "Lists the API keys of your organization. The signing `secret` is never included — it is returned only once, in the create response. Managed with an operator access token, not an API key.\n", "security": [ { "accessToken": [] } ], "parameters": [ { "in": "query", "name": "fields", "description": "Comma-separated projection of fields to return", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of keys (without secrets)", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "rateLimit": { "type": "integer", "minimum": 0 }, "creationTime": { "type": "string", "format": "date-time" } } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "getApiKeys" } }, "/api/salons": { "get": { "tags": [ "Salons" ], "summary": "List salons", "description": "Lists the salons of your organization. Requires the `salons:read` scope.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "responses": { "200": { "description": "Array of salons", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "currency": { "type": "string" }, "defaultLocale": { "type": "string" }, "timezone": { "type": "string" }, "lastEditTime": { "type": "string", "format": "date-time" } } } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "403": { "description": "API key is missing the `salons:read` scope", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "429": { "description": "API key rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "getApiSalons" } }, "/api/salons/{salonId}": { "get": { "tags": [ "Salons" ], "summary": "Get a salon", "description": "Returns a single salon by id. Readable anonymously, like the by-vanity-name lookup below. An authenticated caller still only sees a salon it owns: salons belonging to another organization respond 404. Requires the `salons:read` scope when called with an API key.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "salonId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The salon", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "currency": { "type": "string" }, "defaultLocale": { "type": "string" }, "timezone": { "type": "string" }, "lastEditTime": { "type": "string", "format": "date-time" } } } } } }, "404": { "description": "Not found (or owned by another organization)", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "getApiSalonsSalonId" } }, "/api/services": { "get": { "tags": [ "Services" ], "summary": "List services", "description": "Lists the services of your organization. Requires the `services:read` scope. Optionally filter by `salonId`.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "query", "name": "salonId", "schema": { "type": "string" } }, { "in": "query", "name": "fields", "description": "Comma-separated projection of fields to return", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of services", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "price": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "duration": { "type": "integer", "minimum": 0 }, "lastEditTime": { "type": "string", "format": "date-time" } } } } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "403": { "description": "API key is missing the `services:read` scope", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "429": { "description": "API key rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "getApiServices" }, "post": { "tags": [ "Services" ], "summary": "Create a service", "description": "Creates a service. Requires the `services:write` scope. Fires the `service.created` webhook.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "The created service", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "price": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "duration": { "type": "integer", "minimum": 0 }, "lastEditTime": { "type": "string", "format": "date-time" } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "postApiServices" } }, "/api/services/{serviceId}": { "get": { "tags": [ "Services" ], "summary": "Get a service", "description": "Returns a single service by id. Services belonging to another organization respond 404. Requires the `services:read` scope.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "serviceId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The service", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "price": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "duration": { "type": "integer", "minimum": 0 }, "lastEditTime": { "type": "string", "format": "date-time" } } } } } }, "404": { "description": "Not found (or owned by another organization)", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "getApiServicesServiceId" }, "put": { "tags": [ "Services" ], "summary": "Update a service", "description": "Updates a service. Requires the `services:write` scope. Services owned by another organization respond 404. Fires the `service.updated` webhook.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "serviceId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The updated service", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "price": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "duration": { "type": "integer", "minimum": 0 }, "lastEditTime": { "type": "string", "format": "date-time" } } } } } }, "404": { "description": "Not found (or owned by another organization)", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "putApiServicesServiceId", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "price": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "duration": { "type": "integer", "minimum": 0 }, "lastEditTime": { "type": "string", "format": "date-time" } } } } } } }, "delete": { "tags": [ "Services" ], "summary": "Delete a service", "description": "Deletes a service by id. Requires the `services:write` scope. Services owned by another organization respond 404.\n", "security": [ { "apiKey": [] }, { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "serviceId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The deleted service id", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "price": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "duration": { "type": "integer", "minimum": 0 }, "lastEditTime": { "type": "string", "format": "date-time" } } } } } }, "404": { "description": "Not found (or owned by another organization)", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "deleteApiServicesServiceId" } }, "/api/webhooksubscriptions": { "get": { "tags": [ "Webhook subscriptions" ], "summary": "List webhook subscriptions", "description": "Webhook subscriptions deliver `appointment.created`, `appointment.updated`, `appointment.deleted`, `client.created`, `client.updated`, `service.created` and `service.updated` events to your server as signed POST requests (`X-Hairdora-Signature: t=,v1=`). An endpoint failing 20 times in a row is disabled automatically. Subscriptions are managed with an operator access token; the `secret` is only returned once, on create.\n", "security": [ { "accessToken": [] } ], "responses": { "200": { "description": "Array of webhook subscriptions (without secrets)", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "creationTime": { "type": "string", "format": "date-time" } } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "getApiWebhooksubscriptions" }, "post": { "tags": [ "Webhook subscriptions" ], "summary": "Create a webhook subscription", "description": "The response includes the signing `secret` exactly once — store it; it cannot be retrieved again.\n", "security": [ { "accessToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "salonId", "url" ], "properties": { "salonId": { "type": "string" }, "url": { "type": "string", "example": "https://example.com/hairdora-webhook" }, "events": { "type": "array", "description": "Empty array subscribes to all events", "items": { "type": "string", "enum": [ "appointment.created", "appointment.updated", "appointment.deleted", "client.created", "client.updated", "service.created", "service.updated" ] } } } } } } }, "responses": { "200": { "description": "The created subscription, including its secret", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "creationTime": { "type": "string", "format": "date-time" } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "postApiWebhooksubscriptions" } }, "/api/webhooksubscriptions/{webhookSubscriptionId}": { "put": { "tags": [ "Webhook subscriptions" ], "summary": "Update a webhook subscription", "description": "`url`, `events` and `active` are editable; the secret and salon are immutable. Re-enabling an auto-disabled endpoint is done by setting `active` back to true.\n", "security": [ { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "webhookSubscriptionId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "The updated subscription (without secret)", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "creationTime": { "type": "string", "format": "date-time" } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "putApiWebhooksubscriptionsWebhookSubscriptionId" }, "delete": { "tags": [ "Webhook subscriptions" ], "summary": "Delete a webhook subscription", "security": [ { "accessToken": [] } ], "parameters": [ { "in": "path", "name": "webhookSubscriptionId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "_id": { "type": "string", "minLength": 1 }, "salonId": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "creationTime": { "type": "string", "format": "date-time" } } } } } }, "default": { "description": "Error response", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "name": { "type": "string" }, "statusCode": { "type": "integer" }, "details": { "type": "object", "additionalProperties": true } } } } } } }, "operationId": "deleteApiWebhooksubscriptionsWebhookSubscriptionId", "description": "Delete a webhook subscription" } } }, "tags": [] }