{
"openapi" : "3.0.1",
"info" : {
"description" : "\nRate limiting — per-account throttling on all /api/external/** endpoints.
\n\n### Policies\n\nTwo policies apply concurrently:\n\n- **Sustained** — a per-account quota refilled continuously over a 1-hour window. The specific quota is assigned per account and may change; read the `RateLimit` response header for the current value.\n- **Spike** — 100 requests per 10 seconds. On exhaustion, there is a 60-second cooldown before the spike bucket recovers.\n\n### Response headers\n\nEvery response (success or failure) includes two headers.\n\n**`RateLimit-Policy`** — describes the active policies, following the IETF [draft-ietf-httpapi-ratelimit-headers](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers) quoted-string format.\n\n```\nFormat: \"\";q=;w=, ...\nExample: RateLimit-Policy: \"sustained\";q=10000;w=3600, \"spike\";q=100;w=10\n```\n\n**`RateLimit`** — current status for whichever policy is closest to exhaustion. The `r` value is the available quota (it can rise as well as fall, depending on the policy), and `t` is the effective window in seconds within which no more than `r` tokens may be spent.\n\n```\nFormat: \"\";r=;t=;os-cost=\nExample: RateLimit: \"spike\";r=87;t=3;os-cost=1\n```\n\nThe `os-cost` parameter is an OpenSpace-specific extension reporting the on-arrival cost of the current request: `1` on accepted requests, `0` on `429` responses (the bucket was not debited).\n\n### Cost model\n\nA request consumes 1 token on arrival. Longer-running requests cost more; the extra cost is charged after the response completes:\n\n- **< 1 second** — 1 token\n- **1 second ≤ duration < 5 seconds** — 2 tokens\n- **≥ 5 seconds** — 5 tokens\n\nExtra cost for slow requests is debited from the bucket internally; the lower available quota is reflected in the `RateLimit` header on subsequent requests.\n\n### Handling `429` responses\n\nA `429 Too Many Requests` response includes:\n\n- `Retry-After` — seconds to wait before retrying (rounded up; always ≥ 1 second).\n- An `application/problem+json` body ([RFC 7807 Problem Details](https://datatracker.ietf.org/doc/html/rfc7807)) with `type`, `title`, `status`, and `detail`.\n\nClients should honor `Retry-After` as a minimum wait, and use exponential backoff with jitter when throttling persists across retries.\n\n ",
"title" : "OpenSpace API",
"version" : "v3.0"
},
"servers" : [ {
"url" : "/",
"description" : "OpenSpace API root"
} ],
"tags" : [ {
"description" : "Webhook subscription rule management APIs",
"name" : "Webhook Rules"
}, {
"description" : "Field notes APIs",
"name" : "Field notes"
}, {
"description" : "ExecutiveView progress data (OS Track) proxied from progress-tracking-api",
"name" : "external-executive-view-controller"
}, {
"description" : "Sites APIs",
"name" : "Sites"
}, {
"description" : "Images APIs",
"name" : "Images"
}, {
"description" : "Reporting APIs",
"name" : "Reports"
}, {
"description" : "Webhook delivery history and redelivery APIs",
"name" : "Webhook Deliveries"
}, {
"description" : "Public configuration values needed before authentication",
"name" : "Global config"
}, {
"description" : "Organizations APIs",
"name" : "Organizations"
}, {
"description" : "Construction phases proxied from the Progress Tracking API",
"name" : "Progress Tracking"
}, {
"description" : "Custom field notes APIs. Beta — subject to change without notification.",
"name" : "Custom Field Notes"
}, {
"description" : "Webhook management APIs for event notifications",
"name" : "Webhooks"
}, {
"description" : "Webhook custom header management APIs",
"name" : "Webhook Headers"
} ],
"paths" : {
"/api/external/v1/global-config" : {
"get" : {
"description" : "Anonymous endpoint returning configuration values needed before authentication.",
"operationId" : "getGlobalConfig",
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalGlobalConfigResponse"
}
}
},
"description" : "OK"
}
},
"summary" : "Get public configuration",
"tags" : [ "Global config" ]
}
},
"/api/external/v1/organizations" : {
"get" : {
"operationId" : "organizations",
"parameters" : [ {
"description" : "Zero-based page index (0..N)",
"in" : "query",
"name" : "page",
"required" : false,
"schema" : {
"minimum" : 0,
"type" : "integer",
"default" : 0
}
}, {
"description" : "The size of the page to be returned",
"in" : "query",
"name" : "size",
"required" : false,
"schema" : {
"minimum" : 1,
"type" : "integer",
"default" : 10
}
}, {
"description" : "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
"in" : "query",
"name" : "sort",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"type" : "string"
}
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalOrganizationsGetResponse"
}
}
},
"description" : "OK"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"content" : {
"application/json" : {
"schema" : {
"required" : [ "error", "message", "redemptionEndpoint", "status" ],
"type" : "object",
"properties" : {
"email" : {
"type" : "string",
"description" : "Email of the one account the phone is bound to but its owner has not yet claimed; absent for a phone-only invitee or when several accounts hold the phone",
"nullable" : true,
"example" : "worker@example.com"
},
"error" : {
"type" : "string",
"description" : "Error code identifying the specific error type",
"example" : "email_capture_required"
},
"fullName" : {
"type" : "string",
"description" : "Optional full name from invitation",
"nullable" : true,
"example" : "James Bond"
},
"message" : {
"type" : "string",
"description" : "Human-readable error message",
"example" : "Please complete registration by providing your email address"
},
"redemptionEndpoint" : {
"type" : "string",
"description" : "Endpoint to complete email capture and finish registration",
"example" : "/api/external/v1/auth/redeem-phone-invitation"
},
"status" : {
"type" : "integer",
"description" : "HTTP status code",
"format" : "int32",
"example" : 403
}
}
}
}
},
"description" : "Forbidden: Partial authentication - email capture required"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Get all organizations",
"tags" : [ "Organizations" ]
}
},
"/api/external/v1/organizations/{organizationId}" : {
"get" : {
"operationId" : "organizationById",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalOrganization"
}
}
},
"description" : "OK"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"content" : {
"application/json" : {
"schema" : {
"required" : [ "error", "message", "redemptionEndpoint", "status" ],
"type" : "object",
"properties" : {
"email" : {
"type" : "string",
"description" : "Email of the one account the phone is bound to but its owner has not yet claimed; absent for a phone-only invitee or when several accounts hold the phone",
"nullable" : true,
"example" : "worker@example.com"
},
"error" : {
"type" : "string",
"description" : "Error code identifying the specific error type",
"example" : "email_capture_required"
},
"fullName" : {
"type" : "string",
"description" : "Optional full name from invitation",
"nullable" : true,
"example" : "James Bond"
},
"message" : {
"type" : "string",
"description" : "Human-readable error message",
"example" : "Please complete registration by providing your email address"
},
"redemptionEndpoint" : {
"type" : "string",
"description" : "Endpoint to complete email capture and finish registration",
"example" : "/api/external/v1/auth/redeem-phone-invitation"
},
"status" : {
"type" : "integer",
"description" : "HTTP status code",
"format" : "int32",
"example" : 403
}
}
}
}
},
"description" : "Forbidden: Partial authentication - email capture required"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Get organization by id",
"tags" : [ "Organizations" ]
}
},
"/api/external/v1/organizations/{organizationId}/sites" : {
"get" : {
"operationId" : "sitesByOrganization",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"description" : "Zero-based page index (0..N)",
"in" : "query",
"name" : "page",
"required" : false,
"schema" : {
"minimum" : 0,
"type" : "integer",
"default" : 0
}
}, {
"description" : "The size of the page to be returned",
"in" : "query",
"name" : "size",
"required" : false,
"schema" : {
"minimum" : 1,
"type" : "integer",
"default" : 10
}
}, {
"description" : "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
"in" : "query",
"name" : "sort",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"type" : "string"
}
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalSitesGetResponse"
}
}
},
"description" : "OK"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"content" : {
"application/json" : {
"schema" : {
"required" : [ "error", "message", "redemptionEndpoint", "status" ],
"type" : "object",
"properties" : {
"email" : {
"type" : "string",
"description" : "Email of the one account the phone is bound to but its owner has not yet claimed; absent for a phone-only invitee or when several accounts hold the phone",
"nullable" : true,
"example" : "worker@example.com"
},
"error" : {
"type" : "string",
"description" : "Error code identifying the specific error type",
"example" : "email_capture_required"
},
"fullName" : {
"type" : "string",
"description" : "Optional full name from invitation",
"nullable" : true,
"example" : "James Bond"
},
"message" : {
"type" : "string",
"description" : "Human-readable error message",
"example" : "Please complete registration by providing your email address"
},
"redemptionEndpoint" : {
"type" : "string",
"description" : "Endpoint to complete email capture and finish registration",
"example" : "/api/external/v1/auth/redeem-phone-invitation"
},
"status" : {
"type" : "integer",
"description" : "HTTP status code",
"format" : "int32",
"example" : 403
}
}
}
}
},
"description" : "Forbidden: Partial authentication - email capture required"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Get all sites by organization",
"tags" : [ "Organizations" ]
}
},
"/api/external/v1/organizations/{organizationId}/webhooks" : {
"get" : {
"description" : "Get all webhooks configured for the specified organization",
"operationId" : "listWebhooks",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhooksGetResponse"
}
}
},
"description" : "Success"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "List webhooks for an organization",
"tags" : [ "Webhooks" ]
},
"post" : {
"description" : "Register a new webhook endpoint for the organization. Newly created webhooks start in the notVerified state and do not receive rule-matched event deliveries until verified via POST /webhooks/{id}/verify.",
"operationId" : "createWebhook",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
} ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookCreateRequest"
}
}
},
"required" : true
},
"responses" : {
"201" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhook"
}
}
},
"description" : "Webhook created"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Create a new webhook",
"tags" : [ "Webhooks" ]
}
},
"/api/external/v1/organizations/{organizationId}/webhooks/{webhookId}" : {
"delete" : {
"description" : "Delete a webhook and all associated rules and headers",
"operationId" : "deleteWebhook",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "webhookId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
} ],
"responses" : {
"204" : {
"description" : "Webhook deleted"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"404" : {
"description" : "Webhook not found"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Delete webhook",
"tags" : [ "Webhooks" ]
},
"get" : {
"description" : "Retrieve details of a specific webhook",
"operationId" : "getWebhook",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "webhookId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhook"
}
}
},
"description" : "Success"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"404" : {
"description" : "Webhook not found"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Get webhook by ID",
"tags" : [ "Webhooks" ]
},
"patch" : {
"description" : "Update webhook configuration. Can be used to pause/resume webhooks by changing status. When the URL is changed, the new URL is verified inline (HMAC-signed probe expecting HTTP 2xx) and the update is rejected with 422 if the probe fails. Pass ?skipVerify=true to save the new URL without probing; verification state is reset to notVerified in that case.",
"operationId" : "updateWebhook",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "webhookId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "query",
"name" : "skipVerify",
"required" : false,
"schema" : {
"type" : "boolean",
"default" : false
}
} ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookUpdateRequest"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhook"
}
}
},
"description" : "Success"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"404" : {
"description" : "Webhook not found"
},
"422" : {
"description" : "URL verification failed"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Update webhook",
"tags" : [ "Webhooks" ]
}
},
"/api/external/v1/organizations/{organizationId}/webhooks/{webhookId}/deliveries" : {
"get" : {
"description" : "Get delivery history for a webhook",
"operationId" : "listDeliveries",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "webhookId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"description" : "Zero-based page index (0..N)",
"in" : "query",
"name" : "page",
"required" : false,
"schema" : {
"minimum" : 0,
"type" : "integer",
"default" : 0
}
}, {
"description" : "The size of the page to be returned",
"in" : "query",
"name" : "size",
"required" : false,
"schema" : {
"minimum" : 1,
"type" : "integer",
"default" : 100
}
}, {
"description" : "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
"in" : "query",
"name" : "sort",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"type" : "string"
}
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookDeliveriesGetResponse"
}
}
},
"description" : "Success"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"404" : {
"description" : "Webhook not found"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "List webhook deliveries",
"tags" : [ "Webhook Deliveries" ]
}
},
"/api/external/v1/organizations/{organizationId}/webhooks/{webhookId}/deliveries/{deliveryId}" : {
"get" : {
"description" : "Get detailed information about a specific delivery including all attempts",
"operationId" : "getDeliveryDetail",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "webhookId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "deliveryId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookDeliveryDetail"
}
}
},
"description" : "Success"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"404" : {
"description" : "Delivery not found"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Get delivery details",
"tags" : [ "Webhook Deliveries" ]
}
},
"/api/external/v1/organizations/{organizationId}/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver" : {
"post" : {
"description" : "Retry delivery of a failed webhook event",
"operationId" : "redeliverEvent",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "webhookId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "deliveryId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookDelivery"
}
}
},
"description" : "Redelivery initiated"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"404" : {
"description" : "Delivery not found"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Redeliver webhook event",
"tags" : [ "Webhook Deliveries" ]
}
},
"/api/external/v1/organizations/{organizationId}/webhooks/{webhookId}/headers" : {
"get" : {
"description" : "Get all custom headers configured for a webhook",
"operationId" : "listHeaders",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "webhookId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookHeadersGetResponse"
}
}
},
"description" : "Success"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"404" : {
"description" : "Webhook not found"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "List webhook headers",
"tags" : [ "Webhook Headers" ]
},
"post" : {
"description" : "Add a custom header to include in webhook requests",
"operationId" : "createHeader",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "webhookId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
} ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookHeaderCreateRequest"
}
}
},
"required" : true
},
"responses" : {
"201" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookHeader"
}
}
},
"description" : "Header created"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"404" : {
"description" : "Webhook not found"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Add webhook header",
"tags" : [ "Webhook Headers" ]
}
},
"/api/external/v1/organizations/{organizationId}/webhooks/{webhookId}/headers/{headerId}" : {
"delete" : {
"description" : "Delete a webhook header",
"operationId" : "deleteHeader",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "webhookId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "headerId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
} ],
"responses" : {
"204" : {
"description" : "Header deleted"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"404" : {
"description" : "Header not found"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Delete webhook header",
"tags" : [ "Webhook Headers" ]
},
"get" : {
"description" : "Retrieve details of a specific webhook header",
"operationId" : "getHeader",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "webhookId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "headerId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookHeader"
}
}
},
"description" : "Success"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"404" : {
"description" : "Header not found"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Get webhook header by ID",
"tags" : [ "Webhook Headers" ]
},
"patch" : {
"description" : "Update a webhook header value",
"operationId" : "updateHeader",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "webhookId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "headerId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
} ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookHeaderUpdateRequest"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookHeader"
}
}
},
"description" : "Success"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"404" : {
"description" : "Header not found"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Update webhook header",
"tags" : [ "Webhook Headers" ]
}
},
"/api/external/v1/organizations/{organizationId}/webhooks/{webhookId}/rules" : {
"get" : {
"description" : "Get all subscription rules for a webhook",
"operationId" : "listRules",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "webhookId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookRulesGetResponse"
}
}
},
"description" : "Success"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"404" : {
"description" : "Webhook not found"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "List webhook rules",
"tags" : [ "Webhook Rules" ]
},
"post" : {
"description" : "Create a new subscription rule for a webhook. Rules define which events trigger webhook deliveries.",
"operationId" : "createRule",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "webhookId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
} ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookRuleCreateRequest"
}
}
},
"required" : true
},
"responses" : {
"201" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookRule"
}
}
},
"description" : "Rule created"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"404" : {
"description" : "Webhook not found"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Create webhook rule",
"tags" : [ "Webhook Rules" ]
}
},
"/api/external/v1/organizations/{organizationId}/webhooks/{webhookId}/rules/{ruleId}" : {
"delete" : {
"description" : "Delete a webhook rule",
"operationId" : "deleteRule",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "webhookId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "ruleId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
} ],
"responses" : {
"204" : {
"description" : "Rule deleted"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"404" : {
"description" : "Rule not found"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Delete webhook rule",
"tags" : [ "Webhook Rules" ]
},
"get" : {
"description" : "Retrieve details of a specific webhook rule",
"operationId" : "getRule",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "webhookId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "ruleId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookRule"
}
}
},
"description" : "Success"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"404" : {
"description" : "Rule not found"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Get webhook rule by ID",
"tags" : [ "Webhook Rules" ]
},
"patch" : {
"description" : "Update an existing webhook rule",
"operationId" : "updateRule",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "webhookId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "ruleId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
} ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookRuleUpdateRequest"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookRule"
}
}
},
"description" : "Success"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"404" : {
"description" : "Rule not found"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Update webhook rule",
"tags" : [ "Webhook Rules" ]
}
},
"/api/external/v1/organizations/{organizationId}/webhooks/{webhookId}/test" : {
"post" : {
"description" : "Send a test event to the webhook endpoint to verify configuration. Creates a field_note:created event for the specified field note. Test events bypass the verification gate — they are dispatched even when verificationState is notVerified / verificationError, as long as the webhook is ENABLED. Use /test to debug endpoint configuration before /verify succeeds.",
"operationId" : "testWebhook",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "webhookId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
} ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookTestRequest"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookTestResponse"
}
}
},
"description" : "Test event sent"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"404" : {
"description" : "Webhook or field note not found"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
},
"503" : {
"description" : "Test service unavailable"
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Test webhook",
"tags" : [ "Webhooks" ]
}
},
"/api/external/v1/organizations/{organizationId}/webhooks/{webhookId}/update-secret" : {
"post" : {
"description" : "Rotate the secret token used for HMAC signatures. With the default skipVerify=false, the endpoint is probed with the new secret before persistence: on success the new secret is saved and verificationState is set to verified; on failure the rotation is rejected with 422 and the old secret stays in place. Pass ?skipVerify=true to save the secret without probing — state is reset to notVerified. Use the skipVerify escape hatch when the endpoint is known to be unreachable but rotation must still complete (e.g. suspected secret leak).",
"operationId" : "updateWebhookSecret",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "webhookId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "query",
"name" : "skipVerify",
"required" : false,
"schema" : {
"type" : "boolean",
"default" : false
}
} ],
"requestBody" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookUpdateSecretRequest"
}
}
},
"required" : true
},
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhook"
}
}
},
"description" : "Secret updated"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"404" : {
"description" : "Webhook not found"
},
"422" : {
"description" : "Verification probe failed"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Update webhook secret",
"tags" : [ "Webhooks" ]
}
},
"/api/external/v1/organizations/{organizationId}/webhooks/{webhookId}/verify" : {
"post" : {
"description" : "Send a signed verification probe to the webhook URL. Updates verification_state based on the response. Required before the webhook can receive event deliveries.",
"operationId" : "verifyWebhook",
"parameters" : [ {
"in" : "path",
"name" : "organizationId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "webhookId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalWebhookVerifyResponse"
}
}
},
"description" : "Webhook verified"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"description" : "Forbidden"
},
"404" : {
"description" : "Webhook not found"
},
"422" : {
"description" : "Verification failed"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Verify a webhook endpoint",
"tags" : [ "Webhooks" ]
}
},
"/api/external/v1/reports/360-videos" : {
"get" : {
"operationId" : "getReporting360Videos",
"parameters" : [ {
"description" : "Video started after",
"example" : "2020-01-01T12:00:00Z",
"in" : "query",
"name" : "videoStartedAfter",
"required" : false,
"schema" : {
"type" : "string",
"format" : "date-time"
}
}, {
"description" : "Organization ids to select",
"in" : "query",
"name" : "orgs",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}
}, {
"description" : "Zero-based page index (0..N)",
"in" : "query",
"name" : "page",
"required" : false,
"schema" : {
"minimum" : 0,
"type" : "integer",
"default" : 0
}
}, {
"description" : "The size of the page to be returned",
"in" : "query",
"name" : "size",
"required" : false,
"schema" : {
"minimum" : 1,
"type" : "integer",
"default" : 10
}
}, {
"description" : "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
"in" : "query",
"name" : "sort",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"type" : "string",
"enum" : [ "videoStart", "videoStart,ASC", "videoStart,DESC", "orgName", "orgName,ASC", "orgName,DESC", "siteName", "siteName,ASC", "siteName,DESC", "sheetName", "sheetName,ASC", "sheetName,DESC", "sheetCreated", "sheetCreated,ASC", "sheetCreated,DESC", "sheetDisplayOrder", "sheetDisplayOrder,ASC", "sheetDisplayOrder,DESC", "orgCreated", "orgCreated,ASC", "orgCreated,DESC", "orgUpdated", "orgUpdated,ASC", "orgUpdated,DESC", "siteCreated", "siteCreated,ASC", "siteCreated,DESC" ]
},
"default" : [ "videoStart,DESC" ]
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Reporting360VideoPageResponse"
}
}
},
"description" : "OK"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"content" : {
"application/json" : {
"schema" : {
"required" : [ "error", "message", "redemptionEndpoint", "status" ],
"type" : "object",
"properties" : {
"email" : {
"type" : "string",
"description" : "Email of the one account the phone is bound to but its owner has not yet claimed; absent for a phone-only invitee or when several accounts hold the phone",
"nullable" : true,
"example" : "worker@example.com"
},
"error" : {
"type" : "string",
"description" : "Error code identifying the specific error type",
"example" : "email_capture_required"
},
"fullName" : {
"type" : "string",
"description" : "Optional full name from invitation",
"nullable" : true,
"example" : "James Bond"
},
"message" : {
"type" : "string",
"description" : "Human-readable error message",
"example" : "Please complete registration by providing your email address"
},
"redemptionEndpoint" : {
"type" : "string",
"description" : "Endpoint to complete email capture and finish registration",
"example" : "/api/external/v1/auth/redeem-phone-invitation"
},
"status" : {
"type" : "integer",
"description" : "HTTP status code",
"format" : "int32",
"example" : 403
}
}
}
}
},
"description" : "Forbidden: Partial authentication - email capture required"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Get all accessible 360 videos.",
"tags" : [ "Reports" ]
}
},
"/api/external/v1/reports/drone-images" : {
"get" : {
"operationId" : "getReportingDroneImages",
"parameters" : [ {
"description" : "Drone capture created after",
"example" : "2020-01-01T12:00:00Z",
"in" : "query",
"name" : "droneCaptureCreatedAfter",
"required" : false,
"schema" : {
"type" : "string",
"format" : "date-time"
}
}, {
"description" : "Organization ids to select",
"in" : "query",
"name" : "orgs",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}
}, {
"description" : "Zero-based page index (0..N)",
"in" : "query",
"name" : "page",
"required" : false,
"schema" : {
"minimum" : 0,
"type" : "integer",
"default" : 0
}
}, {
"description" : "The size of the page to be returned",
"in" : "query",
"name" : "size",
"required" : false,
"schema" : {
"minimum" : 1,
"type" : "integer",
"default" : 10
}
}, {
"description" : "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
"in" : "query",
"name" : "sort",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"type" : "string",
"enum" : [ "droneCaptureCreated", "droneCaptureCreated,ASC", "droneCaptureCreated,DESC", "droneImageCreated", "droneImageCreated,ASC", "droneImageCreated,DESC", "orgName", "orgName,ASC", "orgName,DESC", "siteName", "siteName,ASC", "siteName,DESC", "orgCreated", "orgCreated,ASC", "orgCreated,DESC", "orgUpdated", "orgUpdated,ASC", "orgUpdated,DESC", "siteCreated", "siteCreated,ASC", "siteCreated,DESC" ]
},
"default" : [ "droneCaptureCreated,DESC" ]
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ReportingDroneImagePageResponse"
}
}
},
"description" : "OK"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"content" : {
"application/json" : {
"schema" : {
"required" : [ "error", "message", "redemptionEndpoint", "status" ],
"type" : "object",
"properties" : {
"email" : {
"type" : "string",
"description" : "Email of the one account the phone is bound to but its owner has not yet claimed; absent for a phone-only invitee or when several accounts hold the phone",
"nullable" : true,
"example" : "worker@example.com"
},
"error" : {
"type" : "string",
"description" : "Error code identifying the specific error type",
"example" : "email_capture_required"
},
"fullName" : {
"type" : "string",
"description" : "Optional full name from invitation",
"nullable" : true,
"example" : "James Bond"
},
"message" : {
"type" : "string",
"description" : "Human-readable error message",
"example" : "Please complete registration by providing your email address"
},
"redemptionEndpoint" : {
"type" : "string",
"description" : "Endpoint to complete email capture and finish registration",
"example" : "/api/external/v1/auth/redeem-phone-invitation"
},
"status" : {
"type" : "integer",
"description" : "HTTP status code",
"format" : "int32",
"example" : 403
}
}
}
}
},
"description" : "Forbidden: Partial authentication - email capture required"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Get all accessible drone images.",
"tags" : [ "Reports" ]
}
},
"/api/external/v1/reports/field-notes" : {
"get" : {
"operationId" : "getReportingFieldNotes",
"parameters" : [ {
"description" : "Field note updated after",
"example" : "2020-01-01T12:00:00Z",
"in" : "query",
"name" : "fieldNoteUpdatedAfter",
"required" : false,
"schema" : {
"type" : "string",
"format" : "date-time"
}
}, {
"description" : "Organization ids to select",
"in" : "query",
"name" : "orgs",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}
}, {
"description" : "Zero-based page index (0..N)",
"in" : "query",
"name" : "page",
"required" : false,
"schema" : {
"minimum" : 0,
"type" : "integer",
"default" : 0
}
}, {
"description" : "The size of the page to be returned",
"in" : "query",
"name" : "size",
"required" : false,
"schema" : {
"minimum" : 1,
"type" : "integer",
"default" : 10
}
}, {
"description" : "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
"in" : "query",
"name" : "sort",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"type" : "string",
"enum" : [ "fieldNoteCreated", "fieldNoteCreated,ASC", "fieldNoteCreated,DESC", "fieldNoteUpdated", "fieldNoteUpdated,ASC", "fieldNoteUpdated,DESC", "orgName", "orgName,ASC", "orgName,DESC", "siteName", "siteName,ASC", "siteName,DESC", "sheetName", "sheetName,ASC", "sheetName,DESC", "sheetCreated", "sheetCreated,ASC", "sheetCreated,DESC", "sheetDisplayOrder", "sheetDisplayOrder,ASC", "sheetDisplayOrder,DESC", "orgCreated", "orgCreated,ASC", "orgCreated,DESC", "orgUpdated", "orgUpdated,ASC", "orgUpdated,DESC", "siteCreated", "siteCreated,ASC", "siteCreated,DESC" ]
},
"default" : [ "fieldNoteUpdated,DESC" ]
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ReportingFieldNotePageResponse"
}
}
},
"description" : "OK"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"content" : {
"application/json" : {
"schema" : {
"required" : [ "error", "message", "redemptionEndpoint", "status" ],
"type" : "object",
"properties" : {
"email" : {
"type" : "string",
"description" : "Email of the one account the phone is bound to but its owner has not yet claimed; absent for a phone-only invitee or when several accounts hold the phone",
"nullable" : true,
"example" : "worker@example.com"
},
"error" : {
"type" : "string",
"description" : "Error code identifying the specific error type",
"example" : "email_capture_required"
},
"fullName" : {
"type" : "string",
"description" : "Optional full name from invitation",
"nullable" : true,
"example" : "James Bond"
},
"message" : {
"type" : "string",
"description" : "Human-readable error message",
"example" : "Please complete registration by providing your email address"
},
"redemptionEndpoint" : {
"type" : "string",
"description" : "Endpoint to complete email capture and finish registration",
"example" : "/api/external/v1/auth/redeem-phone-invitation"
},
"status" : {
"type" : "integer",
"description" : "HTTP status code",
"format" : "int32",
"example" : 403
}
}
}
}
},
"description" : "Forbidden: Partial authentication - email capture required"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Get all accessible field notes.",
"tags" : [ "Reports" ]
}
},
"/api/external/v1/reports/memberships" : {
"get" : {
"operationId" : "getMemberships",
"parameters" : [ {
"description" : "Organization ids to select",
"in" : "query",
"name" : "orgs",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}
}, {
"description" : "Zero-based page index (0..N)",
"in" : "query",
"name" : "page",
"required" : false,
"schema" : {
"minimum" : 0,
"type" : "integer",
"default" : 0
}
}, {
"description" : "The size of the page to be returned",
"in" : "query",
"name" : "size",
"required" : false,
"schema" : {
"minimum" : 1,
"type" : "integer",
"default" : 10
}
}, {
"description" : "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
"in" : "query",
"name" : "sort",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"type" : "string",
"enum" : [ "email", "email,ASC", "email,DESC", "membershipUpdated", "membershipUpdated,ASC", "membershipUpdated,DESC", "membershipCreated", "membershipCreated,ASC", "membershipCreated,DESC", "orgName", "orgName,ASC", "orgName,DESC", "siteName", "siteName,ASC", "siteName,DESC", "orgCreated", "orgCreated,ASC", "orgCreated,DESC", "orgUpdated", "orgUpdated,ASC", "orgUpdated,DESC", "siteCreated", "siteCreated,ASC", "siteCreated,DESC" ]
},
"default" : [ "email,ASC" ]
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ReportingMembershipPageResponse"
}
}
},
"description" : "OK"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"content" : {
"application/json" : {
"schema" : {
"required" : [ "error", "message", "redemptionEndpoint", "status" ],
"type" : "object",
"properties" : {
"email" : {
"type" : "string",
"description" : "Email of the one account the phone is bound to but its owner has not yet claimed; absent for a phone-only invitee or when several accounts hold the phone",
"nullable" : true,
"example" : "worker@example.com"
},
"error" : {
"type" : "string",
"description" : "Error code identifying the specific error type",
"example" : "email_capture_required"
},
"fullName" : {
"type" : "string",
"description" : "Optional full name from invitation",
"nullable" : true,
"example" : "James Bond"
},
"message" : {
"type" : "string",
"description" : "Human-readable error message",
"example" : "Please complete registration by providing your email address"
},
"redemptionEndpoint" : {
"type" : "string",
"description" : "Endpoint to complete email capture and finish registration",
"example" : "/api/external/v1/auth/redeem-phone-invitation"
},
"status" : {
"type" : "integer",
"description" : "HTTP status code",
"format" : "int32",
"example" : 403
}
}
}
}
},
"description" : "Forbidden: Partial authentication - email capture required"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Get all accessible memberships. Limited to organization administrators.",
"tags" : [ "Reports" ]
}
},
"/api/external/v1/reports/organizations" : {
"get" : {
"operationId" : "getReportingOrganizations",
"parameters" : [ {
"description" : "Organization updated after",
"example" : "2020-01-01T12:00:00Z",
"in" : "query",
"name" : "organizationUpdatedAfter",
"required" : false,
"schema" : {
"type" : "string",
"format" : "date-time"
}
}, {
"description" : "Organization ids to select",
"in" : "query",
"name" : "orgs",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}
}, {
"description" : "Zero-based page index (0..N)",
"in" : "query",
"name" : "page",
"required" : false,
"schema" : {
"minimum" : 0,
"type" : "integer",
"default" : 0
}
}, {
"description" : "The size of the page to be returned",
"in" : "query",
"name" : "size",
"required" : false,
"schema" : {
"minimum" : 1,
"type" : "integer",
"default" : 10
}
}, {
"description" : "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
"in" : "query",
"name" : "sort",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"type" : "string",
"enum" : [ "orgName", "orgName,ASC", "orgName,DESC", "orgCreated", "orgCreated,ASC", "orgCreated,DESC", "orgUpdated", "orgUpdated,ASC", "orgUpdated,DESC" ]
},
"default" : [ "orgUpdated,DESC" ]
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/GetReportingOrganizationsResponse"
}
}
},
"description" : "OK"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"content" : {
"application/json" : {
"schema" : {
"required" : [ "error", "message", "redemptionEndpoint", "status" ],
"type" : "object",
"properties" : {
"email" : {
"type" : "string",
"description" : "Email of the one account the phone is bound to but its owner has not yet claimed; absent for a phone-only invitee or when several accounts hold the phone",
"nullable" : true,
"example" : "worker@example.com"
},
"error" : {
"type" : "string",
"description" : "Error code identifying the specific error type",
"example" : "email_capture_required"
},
"fullName" : {
"type" : "string",
"description" : "Optional full name from invitation",
"nullable" : true,
"example" : "James Bond"
},
"message" : {
"type" : "string",
"description" : "Human-readable error message",
"example" : "Please complete registration by providing your email address"
},
"redemptionEndpoint" : {
"type" : "string",
"description" : "Endpoint to complete email capture and finish registration",
"example" : "/api/external/v1/auth/redeem-phone-invitation"
},
"status" : {
"type" : "integer",
"description" : "HTTP status code",
"format" : "int32",
"example" : 403
}
}
}
}
},
"description" : "Forbidden: Partial authentication - email capture required"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Get all accessible organizations.",
"tags" : [ "Reports" ]
}
},
"/api/external/v1/reports/sheets" : {
"get" : {
"operationId" : "getReportingSheets",
"parameters" : [ {
"description" : "Sheet created after",
"example" : "2020-01-01T12:00:00Z",
"in" : "query",
"name" : "sheetCreatedAfter",
"required" : false,
"schema" : {
"type" : "string",
"format" : "date-time"
}
}, {
"description" : "Organization ids to select",
"in" : "query",
"name" : "orgs",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}
}, {
"description" : "Zero-based page index (0..N)",
"in" : "query",
"name" : "page",
"required" : false,
"schema" : {
"minimum" : 0,
"type" : "integer",
"default" : 0
}
}, {
"description" : "The size of the page to be returned",
"in" : "query",
"name" : "size",
"required" : false,
"schema" : {
"minimum" : 1,
"type" : "integer",
"default" : 10
}
}, {
"description" : "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
"in" : "query",
"name" : "sort",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"type" : "string",
"enum" : [ "orgName", "orgName,ASC", "orgName,DESC", "siteName", "siteName,ASC", "siteName,DESC", "sheetName", "sheetName,ASC", "sheetName,DESC", "sheetCreated", "sheetCreated,ASC", "sheetCreated,DESC", "sheetDisplayOrder", "sheetDisplayOrder,ASC", "sheetDisplayOrder,DESC", "orgCreated", "orgCreated,ASC", "orgCreated,DESC", "orgUpdated", "orgUpdated,ASC", "orgUpdated,DESC", "siteCreated", "siteCreated,ASC", "siteCreated,DESC" ]
},
"default" : [ "sheetCreated,DESC" ]
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/GetReportingSheetPageResponse"
}
}
},
"description" : "OK"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"content" : {
"application/json" : {
"schema" : {
"required" : [ "error", "message", "redemptionEndpoint", "status" ],
"type" : "object",
"properties" : {
"email" : {
"type" : "string",
"description" : "Email of the one account the phone is bound to but its owner has not yet claimed; absent for a phone-only invitee or when several accounts hold the phone",
"nullable" : true,
"example" : "worker@example.com"
},
"error" : {
"type" : "string",
"description" : "Error code identifying the specific error type",
"example" : "email_capture_required"
},
"fullName" : {
"type" : "string",
"description" : "Optional full name from invitation",
"nullable" : true,
"example" : "James Bond"
},
"message" : {
"type" : "string",
"description" : "Human-readable error message",
"example" : "Please complete registration by providing your email address"
},
"redemptionEndpoint" : {
"type" : "string",
"description" : "Endpoint to complete email capture and finish registration",
"example" : "/api/external/v1/auth/redeem-phone-invitation"
},
"status" : {
"type" : "integer",
"description" : "HTTP status code",
"format" : "int32",
"example" : 403
}
}
}
}
},
"description" : "Forbidden: Partial authentication - email capture required"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Get all accessible sheets.",
"tags" : [ "Reports" ]
}
},
"/api/external/v1/reports/site-events" : {
"get" : {
"operationId" : "getReportingSiteEvents",
"parameters" : [ {
"description" : "Site event created after",
"example" : "2020-01-01T12:00:00Z",
"in" : "query",
"name" : "siteEventCreatedAfter",
"required" : false,
"schema" : {
"type" : "string",
"format" : "date-time"
}
}, {
"description" : "Organization ids to select",
"in" : "query",
"name" : "orgs",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}
}, {
"description" : "Zero-based page index (0..N)",
"in" : "query",
"name" : "page",
"required" : false,
"schema" : {
"minimum" : 0,
"type" : "integer",
"default" : 0
}
}, {
"description" : "The size of the page to be returned",
"in" : "query",
"name" : "size",
"required" : false,
"schema" : {
"minimum" : 1,
"type" : "integer",
"default" : 10
}
}, {
"description" : "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
"in" : "query",
"name" : "sort",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"type" : "string",
"enum" : [ "orgName", "orgName,ASC", "orgName,DESC", "orgCreated", "orgCreated,ASC", "orgCreated,DESC", "orgUpdated", "orgUpdated,ASC", "orgUpdated,DESC", "siteName", "siteName,ASC", "siteName,DESC", "siteCreated", "siteCreated,ASC", "siteCreated,DESC", "siteEventCreated", "siteEventCreated,ASC", "siteEventCreated,DESC" ]
},
"default" : [ "siteEventCreated,DESC" ]
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/GetReportingSiteEventPageResponse"
}
}
},
"description" : "OK"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"content" : {
"application/json" : {
"schema" : {
"required" : [ "error", "message", "redemptionEndpoint", "status" ],
"type" : "object",
"properties" : {
"email" : {
"type" : "string",
"description" : "Email of the one account the phone is bound to but its owner has not yet claimed; absent for a phone-only invitee or when several accounts hold the phone",
"nullable" : true,
"example" : "worker@example.com"
},
"error" : {
"type" : "string",
"description" : "Error code identifying the specific error type",
"example" : "email_capture_required"
},
"fullName" : {
"type" : "string",
"description" : "Optional full name from invitation",
"nullable" : true,
"example" : "James Bond"
},
"message" : {
"type" : "string",
"description" : "Human-readable error message",
"example" : "Please complete registration by providing your email address"
},
"redemptionEndpoint" : {
"type" : "string",
"description" : "Endpoint to complete email capture and finish registration",
"example" : "/api/external/v1/auth/redeem-phone-invitation"
},
"status" : {
"type" : "integer",
"description" : "HTTP status code",
"format" : "int32",
"example" : 403
}
}
}
}
},
"description" : "Forbidden: Partial authentication - email capture required"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Get all accessible site events. Limited to organization administrators, and to one event per user per day.",
"tags" : [ "Reports" ]
}
},
"/api/external/v1/reports/sites" : {
"get" : {
"operationId" : "getReportingSites",
"parameters" : [ {
"description" : "Site created after",
"example" : "2020-01-01T12:00:00Z",
"in" : "query",
"name" : "siteCreatedAfter",
"required" : false,
"schema" : {
"type" : "string",
"format" : "date-time"
}
}, {
"description" : "Organization ids to select",
"in" : "query",
"name" : "orgs",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}
}, {
"description" : "Zero-based page index (0..N)",
"in" : "query",
"name" : "page",
"required" : false,
"schema" : {
"minimum" : 0,
"type" : "integer",
"default" : 0
}
}, {
"description" : "The size of the page to be returned",
"in" : "query",
"name" : "size",
"required" : false,
"schema" : {
"minimum" : 1,
"type" : "integer",
"default" : 10
}
}, {
"description" : "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
"in" : "query",
"name" : "sort",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"type" : "string",
"enum" : [ "orgName", "orgName,ASC", "orgName,DESC", "orgCreated", "orgCreated,ASC", "orgCreated,DESC", "orgUpdated", "orgUpdated,ASC", "orgUpdated,DESC", "siteName", "siteName,ASC", "siteName,DESC", "siteCreated", "siteCreated,ASC", "siteCreated,DESC" ]
},
"default" : [ "siteCreated,DESC" ]
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/GetReportingSitePageResponse"
}
}
},
"description" : "OK"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"content" : {
"application/json" : {
"schema" : {
"required" : [ "error", "message", "redemptionEndpoint", "status" ],
"type" : "object",
"properties" : {
"email" : {
"type" : "string",
"description" : "Email of the one account the phone is bound to but its owner has not yet claimed; absent for a phone-only invitee or when several accounts hold the phone",
"nullable" : true,
"example" : "worker@example.com"
},
"error" : {
"type" : "string",
"description" : "Error code identifying the specific error type",
"example" : "email_capture_required"
},
"fullName" : {
"type" : "string",
"description" : "Optional full name from invitation",
"nullable" : true,
"example" : "James Bond"
},
"message" : {
"type" : "string",
"description" : "Human-readable error message",
"example" : "Please complete registration by providing your email address"
},
"redemptionEndpoint" : {
"type" : "string",
"description" : "Endpoint to complete email capture and finish registration",
"example" : "/api/external/v1/auth/redeem-phone-invitation"
},
"status" : {
"type" : "integer",
"description" : "HTTP status code",
"format" : "int32",
"example" : 403
}
}
}
}
},
"description" : "Forbidden: Partial authentication - email capture required"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Get all accessible sites.",
"tags" : [ "Reports" ]
}
},
"/api/external/v1/sites/{siteId}" : {
"get" : {
"operationId" : "getSite",
"parameters" : [ {
"in" : "path",
"name" : "siteId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "query",
"name" : "include",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"type" : "string",
"enum" : [ "accounts", "organization", "eligibleFieldNoteWatcherIds" ]
}
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalSiteGetResponse"
}
}
},
"description" : "OK"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"content" : {
"application/json" : {
"schema" : {
"required" : [ "error", "message", "redemptionEndpoint", "status" ],
"type" : "object",
"properties" : {
"email" : {
"type" : "string",
"description" : "Email of the one account the phone is bound to but its owner has not yet claimed; absent for a phone-only invitee or when several accounts hold the phone",
"nullable" : true,
"example" : "worker@example.com"
},
"error" : {
"type" : "string",
"description" : "Error code identifying the specific error type",
"example" : "email_capture_required"
},
"fullName" : {
"type" : "string",
"description" : "Optional full name from invitation",
"nullable" : true,
"example" : "James Bond"
},
"message" : {
"type" : "string",
"description" : "Human-readable error message",
"example" : "Please complete registration by providing your email address"
},
"redemptionEndpoint" : {
"type" : "string",
"description" : "Endpoint to complete email capture and finish registration",
"example" : "/api/external/v1/auth/redeem-phone-invitation"
},
"status" : {
"type" : "integer",
"description" : "HTTP status code",
"format" : "int32",
"example" : 403
}
}
}
}
},
"description" : "Forbidden: Partial authentication - email capture required"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Get site",
"tags" : [ "Sites" ]
}
},
"/api/external/v1/sites/{siteId}/captures" : {
"get" : {
"operationId" : "capturesBySite",
"parameters" : [ {
"in" : "path",
"name" : "siteId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "query",
"name" : "publishedSince",
"required" : false,
"schema" : {
"type" : "string",
"format" : "date-time"
}
}, {
"description" : "Zero-based page index (0..N)",
"in" : "query",
"name" : "page",
"required" : false,
"schema" : {
"minimum" : 0,
"type" : "integer",
"default" : 0
}
}, {
"description" : "The size of the page to be returned",
"in" : "query",
"name" : "size",
"required" : false,
"schema" : {
"minimum" : 1,
"type" : "integer",
"default" : 1000
}
}, {
"description" : "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
"in" : "query",
"name" : "sort",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"type" : "string"
}
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalCapturesGetResponse"
}
}
},
"description" : "OK"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"content" : {
"application/json" : {
"schema" : {
"required" : [ "error", "message", "redemptionEndpoint", "status" ],
"type" : "object",
"properties" : {
"email" : {
"type" : "string",
"description" : "Email of the one account the phone is bound to but its owner has not yet claimed; absent for a phone-only invitee or when several accounts hold the phone",
"nullable" : true,
"example" : "worker@example.com"
},
"error" : {
"type" : "string",
"description" : "Error code identifying the specific error type",
"example" : "email_capture_required"
},
"fullName" : {
"type" : "string",
"description" : "Optional full name from invitation",
"nullable" : true,
"example" : "James Bond"
},
"message" : {
"type" : "string",
"description" : "Human-readable error message",
"example" : "Please complete registration by providing your email address"
},
"redemptionEndpoint" : {
"type" : "string",
"description" : "Endpoint to complete email capture and finish registration",
"example" : "/api/external/v1/auth/redeem-phone-invitation"
},
"status" : {
"type" : "integer",
"description" : "HTTP status code",
"format" : "int32",
"example" : 403
}
}
}
}
},
"description" : "Forbidden: Partial authentication - email capture required"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Get all captures by site",
"tags" : [ "Sites" ]
}
},
"/api/external/v1/sites/{siteId}/captures/{captureId}" : {
"get" : {
"operationId" : "capturesById",
"parameters" : [ {
"in" : "path",
"name" : "siteId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "captureId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "query",
"name" : "include",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"type" : "string",
"enum" : [ "site", "sheet" ]
}
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalCaptureGetResponse"
}
}
},
"description" : "OK"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"content" : {
"application/json" : {
"schema" : {
"required" : [ "error", "message", "redemptionEndpoint", "status" ],
"type" : "object",
"properties" : {
"email" : {
"type" : "string",
"description" : "Email of the one account the phone is bound to but its owner has not yet claimed; absent for a phone-only invitee or when several accounts hold the phone",
"nullable" : true,
"example" : "worker@example.com"
},
"error" : {
"type" : "string",
"description" : "Error code identifying the specific error type",
"example" : "email_capture_required"
},
"fullName" : {
"type" : "string",
"description" : "Optional full name from invitation",
"nullable" : true,
"example" : "James Bond"
},
"message" : {
"type" : "string",
"description" : "Human-readable error message",
"example" : "Please complete registration by providing your email address"
},
"redemptionEndpoint" : {
"type" : "string",
"description" : "Endpoint to complete email capture and finish registration",
"example" : "/api/external/v1/auth/redeem-phone-invitation"
},
"status" : {
"type" : "integer",
"description" : "HTTP status code",
"format" : "int32",
"example" : 403
}
}
}
}
},
"description" : "Forbidden: Partial authentication - email capture required"
},
"404" : {
"description" : "Not found"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Get capture by id",
"tags" : [ "Sites" ]
}
},
"/api/external/v1/sites/{siteId}/captures/{captureId}/panos" : {
"get" : {
"operationId" : "getPanos",
"parameters" : [ {
"in" : "path",
"name" : "siteId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "captureId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"description" : "Zero-based page index (0..N)",
"in" : "query",
"name" : "page",
"required" : false,
"schema" : {
"minimum" : 0,
"type" : "integer",
"default" : 0
}
}, {
"description" : "The size of the page to be returned",
"in" : "query",
"name" : "size",
"required" : false,
"schema" : {
"minimum" : 1,
"type" : "integer",
"default" : 100
}
}, {
"description" : "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
"in" : "query",
"name" : "sort",
"required" : false,
"schema" : {
"type" : "array",
"items" : {
"type" : "string"
}
}
} ],
"responses" : {
"200" : {
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/ExternalPanosGetResponse"
}
}
},
"description" : "OK"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"content" : {
"application/json" : {
"schema" : {
"required" : [ "error", "message", "redemptionEndpoint", "status" ],
"type" : "object",
"properties" : {
"email" : {
"type" : "string",
"description" : "Email of the one account the phone is bound to but its owner has not yet claimed; absent for a phone-only invitee or when several accounts hold the phone",
"nullable" : true,
"example" : "worker@example.com"
},
"error" : {
"type" : "string",
"description" : "Error code identifying the specific error type",
"example" : "email_capture_required"
},
"fullName" : {
"type" : "string",
"description" : "Optional full name from invitation",
"nullable" : true,
"example" : "James Bond"
},
"message" : {
"type" : "string",
"description" : "Human-readable error message",
"example" : "Please complete registration by providing your email address"
},
"redemptionEndpoint" : {
"type" : "string",
"description" : "Endpoint to complete email capture and finish registration",
"example" : "/api/external/v1/auth/redeem-phone-invitation"
},
"status" : {
"type" : "integer",
"description" : "HTTP status code",
"format" : "int32",
"example" : 403
}
}
}
}
},
"description" : "Forbidden: Partial authentication - email capture required"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=;t=;os-cost=`",
"schema" : {
"type" : "string"
}
},
"RateLimit-Policy" : {
"description" : "Active rate-limit policies. Format: `\"\";q=;w=, ...`",
"schema" : {
"type" : "string"
}
},
"Retry-After" : {
"description" : "Seconds to wait before retrying. Always >= 1.",
"schema" : {
"type" : "string"
}
}
}
}
},
"security" : [ {
"api-key" : [ ]
} ],
"summary" : "Get all panos for capture",
"tags" : [ "Sites" ]
}
},
"/api/external/v1/sites/{siteId}/captures/{captureId}/panos/{panoId}/equi" : {
"get" : {
"operationId" : "downloadOrReprojectEquirectangularImage",
"parameters" : [ {
"in" : "path",
"name" : "siteId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "captureId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
}, {
"in" : "path",
"name" : "panoId",
"required" : true,
"schema" : {
"pattern" : "[0-9A-Za-z_-]{22}",
"type" : "string"
}
} ],
"responses" : {
"200" : {
"content" : {
"application/vnd.openspace.signed-url+json" : { },
"image/jpeg" : { }
},
"description" : "OK"
},
"302" : {
"description" : "Redirect to a location for downloading"
},
"400" : {
"description" : "Bad request"
},
"401" : {
"description" : "Unauthorized"
},
"403" : {
"content" : {
"application/json" : {
"schema" : {
"required" : [ "error", "message", "redemptionEndpoint", "status" ],
"type" : "object",
"properties" : {
"email" : {
"type" : "string",
"description" : "Email of the one account the phone is bound to but its owner has not yet claimed; absent for a phone-only invitee or when several accounts hold the phone",
"nullable" : true,
"example" : "worker@example.com"
},
"error" : {
"type" : "string",
"description" : "Error code identifying the specific error type",
"example" : "email_capture_required"
},
"fullName" : {
"type" : "string",
"description" : "Optional full name from invitation",
"nullable" : true,
"example" : "James Bond"
},
"message" : {
"type" : "string",
"description" : "Human-readable error message",
"example" : "Please complete registration by providing your email address"
},
"redemptionEndpoint" : {
"type" : "string",
"description" : "Endpoint to complete email capture and finish registration",
"example" : "/api/external/v1/auth/redeem-phone-invitation"
},
"status" : {
"type" : "integer",
"description" : "HTTP status code",
"format" : "int32",
"example" : 403
}
}
}
}
},
"description" : "Forbidden: Partial authentication - email capture required"
},
"429" : {
"content" : {
"application/problem+json" : {
"schema" : {
"type" : "object",
"properties" : {
"detail" : {
"type" : "string"
},
"instance" : {
"type" : "string",
"format" : "uri"
},
"status" : {
"type" : "integer",
"format" : "int32",
"example" : 429
},
"title" : {
"type" : "string"
},
"type" : {
"type" : "string",
"format" : "uri"
}
}
}
}
},
"description" : "Rate limit exceeded. Honor the `Retry-After` header before retrying.",
"headers" : {
"RateLimit" : {
"description" : "Current status for whichever policy is closest to exhaustion. Format: `\"\";r=