{ "openapi": "3.0.3", "info": { "title": "OpenStudio API", "version": "v1" }, "servers": [ { "url": "https://api.openstudio.one/v1" } ], "paths": { "/ping": { "get": { "summary": "Health check", "security": [ { "UserKey": [] } ], "x-status": "enabled", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Always the literal string \"pong\" \u2014 confirms the API is reachable and your key(s) authenticated successfully." }, "brand_id": { "type": "integer", "description": "Your tenant's brand_id, resolved from whichever key(s) you sent \u2014 a quick way to confirm you're authenticated as the account you expect." }, "user_id": { "type": "integer", "nullable": true, "description": "Resolved from your `X-Api-User-Key`, if you sent one." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/batch": { "post": { "summary": "Bundle up to 20 sub-requests into one HTTP call", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "description": "At most 20 items. Each is dispatched exactly as if you'd called it directly \u2014 same auth, same rate-limit accounting, same everything \u2014 just combined into one round trip for you.", "items": { "type": "object", "properties": { "id": { "type": "string", "required": false, "description": "Your own label for matching a response back to its request. Defaults to the item's position in the array (as a string) if omitted." }, "method": { "type": "string", "required": true, "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ], "description": "The HTTP method for this sub-request." }, "url": { "type": "string", "required": true, "description": "Path relative to `/v1`, e.g. `/tickets/123` or `/tickets/123/replies`. Cannot itself be `/batch` \u2014 no nesting." }, "body": { "type": "object", "required": false, "description": "Only used for `POST`/`PUT`/`PATCH`. Same shape as that endpoint's own documented request body." }, "idempotency_key": { "type": "string", "required": false, "description": "Forwarded as this ONE sub-request's own `Idempotency-Key` header \u2014 retrying the same batch with the same keys makes each write-endpoint sub-request safe to repeat, exactly like sending that header on a direct call. Only has an effect on endpoints that already support it (currently `POST /tickets` and `POST /tickets/{id}/replies`) \u2014 harmless, silently ignored on any other endpoint. Each sub-request needs its own key; there's no single idempotency key for the batch call as a whole." } } } } }, "required": [ "requests" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "responses": { "type": "array", "description": "Same order as your `requests` array (not completion order, even though sub-requests run in parallel). One failed sub-request does not affect the others \u2014 check each one's own `status`/`body`.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Echoes that sub-request's `id` (or its array position, if you didn't supply one)." }, "status": { "type": "integer", "description": "That sub-request's own HTTP status code \u2014 exactly what you'd have gotten calling it directly. ``502`` specifically means the sub-request itself couldn't be completed (a transport-level failure), not that the target endpoint returned ``502``." }, "body": { "type": "object", "description": "That sub-request's own full response envelope (`success`/`data`/`error`) \u2014 identical to what a direct call to that endpoint would return." } } } } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/applications": { "get": { "summary": "List every app you can access", "security": [ { "UserKey": [] } ], "x-status": "enabled", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "sections": { "type": "array", "description": "One entry per sidebar divider (e.g. \"Administration\", \"Data\") \u2014 only dividers with at least one visible app underneath are included.", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "This section's own internal identifier \u2014 not translated, not guaranteed stable across catalog changes." }, "title": { "type": "string", "description": "Same identifier as `key` for a section specifically (sections have no separate display value here) \u2014 already resolved to your account's language for `apps`' own `title`, see below." }, "apps": { "type": "array", "description": "Every visible app/sub-heading under this section, in the same order the web sidebar itself shows them.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "An internal numeric identifier for this app \u2014 the same value the web dashboard's own favorites widget keys its per-app color palette on (`id % 7` against a fixed 7-color set), included so a client can mirror that exactly rather than picking colors some other way. Not meaningful for anything else \u2014 `key` is still the identifier every other endpoint (`favorites`, etc.) expects." }, "key": { "type": "string", "description": "This app's own internal identifier \u2014 the value `POST /v1/favorites` expects as `key` when `can_favorite` is `true`." }, "title": { "type": "string", "description": "Display name, already resolved to your account's own language \u2014 render as-is." }, "url": { "type": "string", "description": "The web dashboard's own internal address for this app. NOT the same string as `key` for most apps." }, "url_type": { "type": "string", "enum": [ "view", "external" ], "description": "`external` opens `url` directly (already a full link); `view` means `url` is a value on the web dashboard's own domain, not a standalone URL. Prefer `mobile_integration` below for deciding HOW to open an app on mobile \u2014 this field alone conflates several cases `mobile_integration` distinguishes (see its own description)." }, "mobile_integration": { "type": "string", "enum": [ "native", "web_os", "web_ext", "external", "dashboard_os" ], "description": "Admin-controlled \u2014 how the mobile app should open this specific app (see `migrations/024_applications_mobile_integration.sql` for the full decision table). `native`: a real native screen exists. `web_os`: opens in-app, attempts SSO sign-in (the default). `web_ext`: opens in-app, but the sign-in bridge is deliberately skipped (out of the OpenStudio session's scope). `external`: a true third-party link \u2014 opens in-app with no sign-in attempt, same handling as `web_ext` but a PERMANENT classification (\"will likely never integrate\") rather than \"not yet.\" `dashboard_os`: a secondary OpenStudio-hosted dashboard under its own top-level route (not the usual `?view=` convention) \u2014 still attempts SSO, just via `url` directly instead of `/?view={key}`. Not meaningful on a node that has `children` (a collapsible group, not a real destination)." }, "icon": { "type": "string", "description": "A raw Font Awesome class name, e.g. `\"fa-address-book\"` \u2014 matches the icon the web dashboard itself shows for this app. Free-form per app, not a fixed enum \u2014 the catalog spans dozens of distinct icons across tenants; render your own fallback for anything you don't recognize rather than assuming full coverage." }, "status": { "type": "integer", "enum": [ 1, 0, -1, -2 ], "description": "`1` = live (generally available). `0` = beta (visible only to callers in the beta-tester group, same gating the web sidebar itself applies before this app is ever included in the response \u2014 a caller outside that group will simply never see a `0` here). `-1` = maintenance (visible, but expect the app itself to be degraded/unavailable). `-2` = dev (alpha/internal-only, same group-gating as beta, one level more restricted)." }, "can_favorite": { "type": "boolean", "description": "`true`: a valid `POST /v1/favorites` target. `false`: shown here (e.g. for browsing/navigation) but rejected as a favorite \u2014 typically a parent/administrative entry rather than something a user would pin to their Home screen. There is no third state." }, "description": { "type": "string", "nullable": true, "description": "A short public-facing blurb, when this app has one. `null`, not `\"\"`, when absent." }, "children": { "type": "array", "description": "This app's own sub-apps, same object shape as this level, one level deep only (a sub-app's own `children` is never populated \u2014 this catalog doesn't nest further than that). Key is ABSENT (not an empty array) when this app has no sub-apps.", "items": { "type": "object" } } } } } } } } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/favorites": { "get": { "summary": "List your favorite apps", "security": [ { "UserKey": [] } ], "x-status": "enabled", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "favorites": { "type": "array", "description": "App keys, in order.", "items": { "type": "string" } } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "post": { "summary": "Add or remove a favorite app", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "description": "An app key from `GET /v1/applications` (must have `can_favorite: true`) or a native-screen shortcut key." } }, "required": [ "key" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "added", "removed" ], "description": "Whether this call added or removed the app from the caller's favorites." }, "favorites": { "type": "array", "description": "The full updated list, in order.", "items": { "type": "string" } } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "patch": { "summary": "Reorder your favorite apps", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "array", "description": "The full, reordered list of favorited app keys, in the new display order.", "items": { "type": "string" } } }, "required": [ "order" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "favorites": { "type": "array", "description": "The full list in its new order.", "items": { "type": "string" } } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol/dashboard": { "get": { "summary": "Get the IT Protocol app's own dashboard", "security": [ { "UserKey": [] } ], "x-status": "enabled", "parameters": [ { "name": "uor", "in": "query", "required": false, "description": "Scope `stats.office` to one specific unit from `available_uors` (matched by `code`), instead of the default aggregated view across every unit you belong to. Silently falls back to the aggregated view if the value isn't one of your own `available_uors`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "stats": { "type": "object", "description": "Your two document-count breakdowns \u2014 see `personal`/`office` below.", "properties": { "personal": { "type": "object", "description": "Your own RPA/CC/folder standing." }, "office": { "type": "object", "description": "Your organizational unit(s)' own standing \u2014 `label` names which unit(s) this breakdown covers (every unit you belong to, aggregated, unless `uor` narrowed it to one)." } } }, "recent_items": { "type": "array", "description": "Up to 6 most-recently-viewed protocol documents/dossiers, newest first.", "items": { "type": "object", "properties": { "doc_type": { "type": "string", "enum": [ "protocol", "dossier" ], "description": "Which detail endpoint this item belongs to \u2014 `protocol` items open via `GET /protocol-documents/{doc_id}`; `dossier` items have no detail endpoint yet." }, "doc_id": { "type": "integer", "nullable": true, "description": "The id to pass to the relevant detail endpoint. Null only if the underlying record was deleted after being viewed." }, "icon": { "type": "string", "description": "A semantic hint (e.g. `inbound`/`outbound`/`internal`/`register`/`folder`), not a font/icon-set name \u2014 render your own icon per value." }, "color": { "type": "string", "enum": [ "accent", "ok", "purple", "warn", "muted" ], "description": "A semantic color hint, not a hex value \u2014 map to your own palette." }, "label": { "type": "string", "description": "Protocol number (e.g. `00015/2026`) or register/dossier identifier, already formatted." }, "subject": { "type": "string", "nullable": true, "description": "The document/dossier's own subject line, as entered at registration." }, "viewed_at": { "type": "string", "description": "MySQL datetime, UTC." } } } }, "available_uors": { "type": "array", "description": "Every unit you belong to \u2014 valid values for the `uor` query param above. Empty if you don't belong to any (the office breakdown is then meaningless and can be hidden entirely).", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "The unit's short code \u2014 pass this as `uor`." }, "title": { "type": "string", "nullable": true, "description": "Display name, when resolvable." } } } } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-documents/{id}": { "get": { "summary": "Get a protocol document \u2014 full detail view", "security": [ { "UserKey": [] } ], "x-status": "enabled", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "document": { "type": "object", "description": "Core fields \u2014 id, box, display_number (zerofilled), date, oggetto (subject), status, visibility level, etc." }, "classification": { "type": "object", "description": "The document's classification \u2014 see also ```GET /reference/protocol-classifications``` for the full pickable list.", "properties": { "var": { "type": "string", "description": "The identifier to submit back to ```POST /protocol-documents/{id}/change-classification``` (as `var`) or ```POST /protocol-registration``` (as `classification`) \u2014 distinct from the human-facing `code` below." }, "code": { "type": "string", "description": "The human-facing roman-numeral/index pair (e.g. `I/4`) \u2014 matches a `classificazione_specifica` row's own `titolo`/`indice`." }, "label": { "type": "string", "description": "The specific classification's own display title, already resolved via `_lang()` \u2014 never the raw underlying label value, which isn't the real display text." }, "general_label": { "type": "string", "nullable": true, "description": "The broader general-classification category this specific one rolls up into (e.g. `code` `I/4` belongs to general category `I`), also `_lang()`-resolved." }, "sensitive": { "type": "boolean", "description": "Whether this document is flagged as containing sensitive personal information." } } }, "correspondent": { "type": "object", "nullable": true, "description": "Sender (arrival/internal) or recipient(s) (departure \u2014 `recipients` array for a multi-recipient document). A sender/recipient carries its own `record_id` \u2014 the registry id to submit back as `correspondent_record_id` on a reply/duplicate registration." }, "attachments": { "type": "array", "description": "File list \u2014 `id` (when present) is usable with ```GET /protocol-documents/{id}/files/{file_id}/download``` to view/download that one file, or use ```GET .../download-all``` for a ZIP of everything.", "items": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true, "description": "The underlying `fileManager.fileId`, when this attachment uses the modern storage path \u2014 null for a legacy raw-URL attachment (not individually downloadable, only via `download-all`)." }, "filename": { "type": "string", "description": "The original filename." }, "archived": { "type": "boolean", "description": "Whether the underlying file has been archived or deleted in storage \u2014 the entry still appears here for a complete record, but the file itself may no longer be retrievable." } } } }, "deadlines": { "type": "array", "description": "Every deadline you can see on this document \u2014 your own personal reminders plus every shared one, matching `GET /protocol-documents/{id}/deadlines`' own visibility rule.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Use this in the deadline sub-routes below." }, "type": { "type": "string", "enum": [ "personal", "shared" ], "description": "A `personal` deadline is visible only to its own creator; a `shared` one is visible to anyone who can see the document." }, "deadline_date": { "type": "string", "description": "YYYY-MM-DD \u2014 when this deadline is due." }, "reminder_date": { "type": "string", "nullable": true, "description": "YYYY-MM-DD \u2014 an optional earlier reminder date, if one was set." }, "description": { "type": "string", "description": "What this deadline is for." }, "notes": { "type": "string", "description": "Free-text notes, separate from `description`." }, "completed": { "type": "boolean", "description": "Whether this deadline has been marked done." }, "completed_by": { "type": "integer", "nullable": true, "description": "The completing user's personal code, when `completed` is true." }, "completed_at": { "type": "string", "nullable": true, "description": "MySQL datetime, UTC, when `completed` is true." }, "can_edit": { "type": "boolean", "description": "Whether YOU can toggle/delete this specific deadline \u2014 its own creator always can; a shared deadline can also be edited by anyone with `action_on_doc`/founder/RPA standing." } } } }, "responsibility": { "type": "object", "description": "Either `rpa` (arrival/departure) or `author`+`original_rpa` (internal), plus `cc` \u2014 an array of CC recipients, each with `can_remove`. Every person object carries `avatar_url` (their real photo, when one exists) and `dep_title` as the FULL Area > Department > Unit hierarchy, not just the immediate structure name." }, "folders": { "type": "array", "description": "Folders (dossiers) this document is linked into.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The dossier id \u2014 use this for the unlink route below." }, "label": { "type": "string", "description": "The folder's own display number (`id_fascicolo/anno`)." }, "subject": { "type": "string", "description": "The folder's own subject line." } } } }, "workflow": { "type": "array", "description": "The document's own workflow log (currently only ever gains a single `close_workflow` entry \u2014 see the close-workflow route below).", "items": { "type": "object", "description": "One workflow event \u2014 `title` (the event name), `dep`/`user_name` (who performed it), `date`." } }, "history": { "type": "array", "description": "The full audit trail for this document \u2014 every write action taken on it, newest first.", "items": { "type": "object", "description": "One audit entry \u2014 `action` (what happened), `extra` (optional detail), `user_name` (who did it), `user_structure` (their CURRENT structure, Area > Unit \u2014 resolved at read time, not a point-in-time snapshot), `created_at`." } }, "notes": { "type": "array", "description": "The annotation thread \u2014 private notes from OTHER people are already filtered out server-side.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "This note's own id." }, "user_id": { "type": "integer", "description": "The author's personal code." }, "user_name": { "type": "string", "description": "The author's display name." }, "note": { "type": "string", "description": "The note text." }, "private": { "type": "boolean", "description": "Whether this note is visible only to its own author (you'll only ever see someone else's private note if it's your own)." }, "is_me": { "type": "boolean", "description": "Whether YOU are this note's author \u2014 lets a client style your own notes differently, same as a chat thread." }, "created_at": { "type": "string", "description": "MySQL datetime, UTC." } } } }, "retention": { "type": "object", "description": "The document's data-retention/conservation policy \u2014 `policy` (e.g. `10_years`), `expires_at`, `action` (what happens on expiry), `migrated`/`migrated_at` (whether it's already been moved to cold storage)." }, "integrity": { "type": "object", "description": "The document's tamper-evidence seal status.", "properties": { "sealed": { "type": "boolean", "description": "Whether a digest has ever been generated for this document \u2014 false for a legacy, never-sealed record." }, "digest": { "type": "string", "nullable": true, "description": "The current digest value, when sealed." } } }, "register": { "type": "object", "nullable": true, "description": "Present only when this document has been promoted onto a register \u2014 `id`, `name`, `repno` (the register-sequence number), `repdate`." }, "can": { "type": "object", "description": "One boolean per tool on the source page \u2014 see this route's own description for what `true` on a not-yet-writable one means." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-documents/{id}/notes": { "post": { "summary": "Add a note/annotation to a document", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string" }, "private": { "type": "boolean", "description": "Visible only to you when true. Defaults to false." } }, "required": [ "note" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-documents/{id}/cc": { "post": { "summary": "Add a CC recipient to a document", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "dep": { "type": "string", "description": "A structure acronym." }, "user": { "type": "string", "description": "A personal code, or empty to CC the whole department (rare, matches the source page's own 'whole UOR/office' option)." } }, "required": [ "dep", "user" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "delete": { "summary": "Remove a CC recipient from a document", "security": [ { "UserKey": [] } ], "x-status": "enabled", "parameters": [ { "name": "dep", "in": "query", "required": false, "description": "Required \u2014 the structure acronym from the CC entry being removed.", "schema": { "type": "string" } }, { "name": "user", "in": "query", "required": false, "description": "Required \u2014 the personal code from the CC entry being removed (empty string for a whole-department CC entry).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-documents/{id}/reject-assignment": { "post": { "summary": "Reject an arrival document's assignment", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Why the assignment is being rejected \u2014 recorded in the document history." } }, "required": [ "reason" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-documents/{id}/change-classification": { "post": { "summary": "Change a document's classification", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "var": { "type": "string", "description": "A real classification identifier, from ```GET /reference/protocol-classifications```'s `specific[].var`." } }, "required": [ "var" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-documents/{id}/request-cancellation": { "post": { "summary": "Request that a document be cancelled (voided)", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Why this document should be cancelled." } }, "required": [ "reason" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-documents/{id}/change-rpa": { "post": { "summary": "Reassign the document's Responsible (RPA)", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "resp_dep": { "type": "string", "description": "The new RPA's structure acronym." }, "resp_user": { "type": "string", "description": "The new RPA's personal code." }, "move_old_rpa_to_cc": { "type": "boolean", "description": "CC the outgoing RPA instead of dropping them from the document. Defaults to false." } }, "required": [ "resp_dep", "resp_user" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-documents/{id}/update-retention": { "post": { "summary": "Update a document's retention (conservation) policy", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "type": "string", "description": "`permanent`, or a number of years as a string, e.g. `10_years`." }, "action": { "type": "string", "description": "`migrate` or `delete` \u2014 what happens once the policy expires. Defaults to `migrate`." } }, "required": [ "policy" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-documents/{id}/registers": { "get": { "summary": "List the registers this document could be assigned to", "security": [ { "UserKey": [] } ], "x-status": "enabled", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "registers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "code": { "type": "string", "nullable": true } } } } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-documents/{id}/assign-register": { "post": { "summary": "Also file this document into a register", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "register_id": { "type": "integer" } }, "required": [ "register_id" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "register_id": { "type": "integer" }, "repno": { "type": "integer", "description": "The newly-assigned register entry number." }, "year": { "type": "integer" } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-documents/{id}/seal": { "post": { "summary": "Generate an integrity seal for a legacy document", "security": [ { "UserKey": [] } ], "x-status": "enabled", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-documents/{id}/download-all": { "get": { "summary": "Download every attached file as a ZIP", "security": [ { "UserKey": [] } ], "x-status": "enabled", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "type": "string", "format": "binary", "description": "The ZIP file, streamed directly (`Content-Type: application/zip`)." } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-documents/{id}/files": { "post": { "summary": "Attach a new file to an already-registered document", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_base64": { "type": "string" }, "filename": { "type": "string" } }, "required": [ "file_base64", "filename" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The new fileManager.fileId." }, "filename": { "type": "string", "description": "The name it was actually saved as \u2014 suffixed if a same-named file already existed." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-documents/{id}/files/{file_id}/download": { "get": { "summary": "Download one attachment", "security": [ { "UserKey": [] } ], "x-status": "enabled", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "type": "string", "format": "binary", "description": "The file, streamed directly with its own real Content-Type." } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-documents/{id}/deadlines": { "post": { "summary": "Add a deadline to a document", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "deadline_date": { "type": "string", "description": "YYYY-MM-DD." }, "description": { "type": "string", "description": "What this deadline is for." }, "notes": { "type": "string", "description": "Free-text notes, separate from `description`." }, "reminder_date": { "type": "string", "description": "YYYY-MM-DD." }, "type": { "type": "string", "enum": [ "personal", "shared" ], "description": "Defaults to personal." } }, "required": [ "deadline_date" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." }, "type": { "type": "string", "description": "The type actually applied \u2014 may differ from the request, see description." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-documents/{id}/deadlines/{deadline_id}": { "patch": { "summary": "Toggle a deadline complete/reopen", "security": [ { "UserKey": [] } ], "x-status": "enabled", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." }, "completed": { "type": "boolean", "description": "The new state after toggling." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "delete": { "summary": "Delete a deadline", "security": [ { "UserKey": [] } ], "x-status": "enabled", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-documents/{id}/close-workflow": { "post": { "summary": "Close a document's workflow", "security": [ { "UserKey": [] } ], "x-status": "enabled", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-documents/{id}/dossiers": { "post": { "summary": "Link a document to a folder (dossier)", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "dossier_id": { "type": "integer", "description": "The target folder's own `id` (from `GET /protocol-dossiers`), not its display number." } }, "required": [ "dossier_id" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-documents/{id}/dossiers/{dossier_id}": { "delete": { "summary": "Unlink a document from a folder (dossier)", "security": [ { "UserKey": [] } ], "x-status": "enabled", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/reference/protocol-classifications": { "get": { "summary": "Get the Protocol app's classification tree", "security": [ { "UserKey": [] } ], "x-status": "enabled", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "general": { "type": "array", "description": "The top-level category list.", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "titolo": { "type": "string", "description": "The roman-numeral group code (e.g. `I`) \u2014 matches `specific[].titolo`." }, "var": { "type": "string", "nullable": true, "description": "The lang_var `label` was resolved from." }, "label": { "type": "string", "description": "Display title, already `_lang()`-resolved." } } } }, "specific": { "type": "array", "description": "The full flat list of specific classifications \u2014 a document's own `classification.code`/`.label` always come from one row here.", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "code": { "type": "string", "description": "`titolo`/`indice` combined \u2014 matches `GET /protocol-documents/{id}`'s own `classification.code`." }, "titolo": { "type": "string", "description": "This row's own group code \u2014 matches a `general[].titolo`." }, "indice": { "type": "string", "description": "The sub-index within that group." }, "var": { "type": "string", "nullable": true, "description": "The lang_var `label` was resolved from \u2014 this is also the exact value a document's own `classification.var` stores." }, "label": { "type": "string", "description": "Display title, already `_lang()`-resolved." } } } } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-dossiers": { "get": { "summary": "Search/list folders (dossiers)", "security": [ { "UserKey": [] } ], "x-status": "enabled", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Substring match against subject, folder number, and notes.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Defaults to `open`.", "schema": { "type": "string", "enum": [ "open", "closed", "all" ] } }, { "name": "classification", "in": "query", "required": false, "description": "Exact match against a specific classification `var` (see `GET /reference/protocol-classifications`).", "schema": { "type": "string" } }, { "name": "my_rpa", "in": "query", "required": false, "description": "Only folders you personally own (RPA). Mirrors the Dashboard's own \"Folders I manage\" stat.", "schema": { "type": "boolean" } }, { "name": "my_cc", "in": "query", "required": false, "description": "Only folders you're personally in CC on. Mirrors the Dashboard's own \"Folders (CC)\" stat.", "schema": { "type": "boolean" } }, { "name": "rpa", "in": "query", "required": false, "description": "Exact match against an arbitrary hr_id \u2014 App Support #572, used for scoping \"which folders can this document link into\" (RPA + classification alignment), distinct from `my_rpa` (always the caller's own id).", "schema": { "type": "string" } }, { "name": "exclude_doc_id", "in": "query", "required": false, "description": "Excludes folders a given document is already linked into.", "schema": { "type": "integer" } }, { "name": "peek_next_id", "in": "query", "required": false, "description": "A completely different, lightweight response shape \u2014 see the dedicated summary below. When set, every other param on this route is ignored.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "dossiers": { "type": "array", "description": "Up to 200 results, newest folder-year/number first.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Use this for `GET /protocol-dossiers/{id}`." }, "label": { "type": "string", "description": "The folder's own display number (`id_fascicolo/anno`)." }, "subject": { "type": "string", "description": "The folder's own subject/title." }, "rpa_user_id": { "type": "integer", "nullable": true, "description": "The owning person's personal code." }, "rpa_user_name": { "type": "string", "nullable": true, "description": "The owning person's display name." }, "uor": { "type": "string", "description": "The owning structure's acronym." }, "uor_title": { "type": "string", "nullable": true, "description": "Display name for `uor`, when resolvable." }, "status": { "type": "integer", "enum": [ 0, 1 ], "description": "0 = open, 1 = closed." }, "document_count": { "type": "integer", "description": "How many documents are linked into this folder." }, "access_reason": { "type": "string", "description": "Why you can see this result (e.g. `RPA (Owner)`, `Department Membership (UOR)`, `CC (Read Only)`) \u2014 same reasons `GET /protocol-dossiers/{id}` itself reports." } } } } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "post": { "summary": "Create a new folder (dossier)", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "oggetto": { "type": "string", "description": "The subject/title." }, "classificazione": { "type": "string", "description": "A specific classification `var`, from `GET /reference/protocol-classifications`." }, "uor": { "type": "string", "description": "The owning structure's acronym." }, "rpa": { "type": "string", "description": "The owning user's personal code." }, "anno": { "type": "integer", "description": "Defaults to the current year." }, "note": { "type": "string", "description": "Free-text notes for the new folder." }, "q_visibility": { "type": "integer", "enum": [ 0, 1, 2, 3 ], "description": "Defaults to 0 (public)." }, "father_id": { "type": "integer", "description": "Makes this a sub-folder of an existing ROOT folder you own \u2014 must itself have no parent and belong to you, same constraint as the source page's own picker." } }, "required": [ "oggetto", "classificazione", "uor", "rpa" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "integer", "description": "The new folder's own id." }, "label": { "type": "string", "description": "The generated display number." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-dossiers/{id}": { "get": { "summary": "Get a folder (dossier) \u2014 full detail view", "security": [ { "UserKey": [] } ], "x-status": "enabled", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "dossier": { "type": "object", "description": "Core fields.", "properties": { "id": { "type": "integer", "description": "This folder's own id \u2014 use it for every sub-route below." }, "label": { "type": "string", "description": "Display number (`id_fascicolo/anno`)." }, "subject": { "type": "string", "description": "The folder's own subject/title." }, "note": { "type": "string", "nullable": true, "description": "Free-text notes." }, "status": { "type": "integer", "enum": [ 0, 1 ], "description": "0 = open, 1 = closed." }, "q_visibility": { "type": "integer", "description": "Same 0-3 visibility scale as a document's own `document.q_visibility`." }, "created_at": { "type": "string", "nullable": true, "description": "MySQL datetime, UTC." }, "closed_at": { "type": "string", "nullable": true, "description": "MySQL datetime, UTC, when `status` is 1." } } }, "classification": { "type": "object", "description": "The folder's classification.", "properties": { "code": { "type": "string", "description": "The `titolo`/`indice` pair, e.g. `I/4`." }, "label": { "type": "string", "description": "Already `_lang()`-resolved \u2014 see `GET /reference/protocol-classifications`'s own note on why this isn't the raw underlying label value." } } }, "rpa": { "type": "object", "description": "The folder's owning structure + person.", "properties": { "dep": { "type": "string", "description": "The owning structure's acronym." }, "dep_title": { "type": "string", "nullable": true, "description": "Display name for `dep`, when resolvable." }, "user_id": { "type": "integer", "nullable": true, "description": "The owning person's personal code." }, "user_name": { "type": "string", "nullable": true, "description": "The owning person's display name." } } }, "created_by": { "type": "object", "description": "Who created this folder.", "properties": { "user_id": { "type": "integer", "nullable": true, "description": "The creator's personal code." }, "user_name": { "type": "string", "nullable": true, "description": "The creator's display name." }, "dep": { "type": "string", "nullable": true, "description": "The creator's own department at the time of creation." } } }, "cc": { "type": "array", "description": "Every CC entry on this folder.", "items": { "type": "object", "properties": { "dep": { "type": "string", "description": "A structure acronym." }, "dep_title": { "type": "string", "nullable": true, "description": "Display name for `dep`, when resolvable." }, "user_id": { "type": "integer", "nullable": true, "description": "A personal code, or null for a whole-department CC entry." }, "user_name": { "type": "string", "nullable": true, "description": "The CC'd person's display name, when `user_id` is set." }, "can_remove": { "type": "boolean", "description": "Whether YOU can remove this specific CC entry." } } } }, "documents": { "type": "array", "description": "Every document linked into this folder.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Use this with ```GET /protocol-documents/{id}```." }, "box": { "type": "string", "description": "The document's own type \u2014 `arrivo`/`uscita`/`interno`." }, "display_number": { "type": "string", "nullable": true, "description": "The document's own protocol number, when it has one (null for a register entry with no protocol number yet)." }, "date": { "type": "string", "description": "The document's own registration date." }, "subject": { "type": "string", "description": "The document's own subject line." }, "mismatch": { "type": "boolean", "description": "True when this document's own department or classification has drifted from the folder's \u2014 the source page's own \"align\" tool (not yet implemented here, see this route's own `can`) fixes this." } } } }, "parent": { "type": "object", "nullable": true, "description": "The folder this one is nested under, if any.", "properties": { "id": { "type": "integer", "description": "The parent folder's own id." }, "label": { "type": "string", "description": "Display number." }, "subject": { "type": "string", "description": "Subject/title." } } }, "children": { "type": "array", "description": "Folders nested directly under this one.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The child folder's own id." }, "label": { "type": "string", "description": "Display number." }, "subject": { "type": "string", "description": "Subject/title." } } } }, "notes": { "type": "array", "description": "The annotation thread \u2014 same shape and same \"others' private notes filtered out\" rule as ```GET /protocol-documents/{id}```'s own `notes`.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "This note's own id." }, "user_id": { "type": "integer", "description": "The author's personal code." }, "user_name": { "type": "string", "description": "The author's display name." }, "note": { "type": "string", "description": "The note text." }, "private": { "type": "boolean", "description": "Whether this note is visible only to its own author." }, "is_me": { "type": "boolean", "description": "Whether YOU are this note's author." }, "created_at": { "type": "string", "description": "MySQL datetime, UTC." } } } }, "history": { "type": "array", "description": "The folder's own audit trail.", "items": { "type": "object", "properties": { "action": { "type": "string", "description": "What happened." }, "user_id": { "type": "integer", "nullable": true, "description": "Who did it." }, "user_name": { "type": "string", "nullable": true, "description": "The actor's display name." }, "user_structure": { "type": "string", "nullable": true, "description": "The actor's CURRENT structure (Area > Unit), resolved at read time." }, "created_at": { "type": "string", "description": "MySQL datetime, UTC." } } } }, "access_reason": { "type": "string", "description": "Why you can see this folder \u2014 see this route's own description." }, "can": { "type": "object", "description": "One boolean per tool \u2014 `true` on `change_rpa`/`change_classification`/`align_mismatched_documents` means you have permission, not that a write endpoint exists yet for it (real, documented scope cut)." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "patch": { "summary": "Update a folder's own subject/notes", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "oggetto": { "type": "string", "description": "Renames the folder." }, "note": { "type": "string", "description": "Replaces the folder's own notes." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-dossiers/{id}/close": { "post": { "summary": "Close a folder", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "description": "Appended to the folder's own notes as a closing remark." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-dossiers/{id}/reopen": { "post": { "summary": "Reopen a closed folder", "security": [ { "UserKey": [] } ], "x-status": "enabled", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-dossiers/{id}/cc": { "post": { "summary": "Add a CC entry to a folder", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "dep": { "type": "string", "description": "A structure acronym." }, "user": { "type": "string", "description": "A personal code. Omit to CC the whole department." } }, "required": [ "dep" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "delete": { "summary": "Remove a CC entry from a folder", "security": [ { "UserKey": [] } ], "x-status": "enabled", "parameters": [ { "name": "dep", "in": "query", "required": false, "description": "Required.", "schema": { "type": "string" } }, { "name": "user", "in": "query", "required": false, "description": "Required (empty string for a whole-department entry).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-dossiers/{id}/notes": { "post": { "summary": "Add a note/annotation to a folder", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "description": "The note text." }, "private": { "type": "boolean", "description": "Visible only to you when true." } }, "required": [ "note" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-dossiers/{id}/eligible-documents": { "get": { "summary": "Search documents this folder could link", "security": [ { "UserKey": [] } ], "x-status": "enabled", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Substring match against subject or protocol number.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "documents": { "type": "array", "description": "Up to 50 matches.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Pass this as `doc_id` to the link route." }, "box": { "type": "string", "description": "The document's own type \u2014 `arrivo`/`uscita`/`interno`." }, "display_number": { "type": "string", "nullable": true, "description": "The document's own protocol number, when it has one." }, "subject": { "type": "string", "description": "The document's own subject line." } } } } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-dossiers/{id}/documents": { "post": { "summary": "Link a document into a folder", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "doc_id": { "type": "integer", "description": "From ```GET /protocol-dossiers/{id}/eligible-documents```." } }, "required": [ "doc_id" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-dossiers/{id}/documents/{document_id}": { "delete": { "summary": "Unlink a document from a folder", "security": [ { "UserKey": [] } ], "x-status": "enabled", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-dossiers/{id}/parent": { "post": { "summary": "Set or clear a folder's parent folder", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "father_id": { "type": "integer", "description": "Omit or `0` to clear." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always true \u2014 a failed attempt returns an error response instead." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/registry": { "get": { "summary": "Search the Registry", "security": [ { "UserKey": [] } ], "x-status": "enabled", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Substring match against the record id, first/last name, and the composite display name.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "description": "Defaults to `all`.", "schema": { "type": "string", "enum": [ "person", "structure", "all" ] } }, { "name": "scope", "in": "query", "required": false, "description": "Defaults to `all`. `internal` means linked to a real system user/structure.", "schema": { "type": "string", "enum": [ "internal", "external", "all" ] } }, { "name": "email", "in": "query", "required": false, "description": "Substring match against email or certified email (PEC).", "schema": { "type": "string" } }, { "name": "city", "in": "query", "required": false, "description": "Substring match against home city, birth city, or home address.", "schema": { "type": "string" } }, { "name": "taxcode", "in": "query", "required": false, "description": "Substring match against fiscal code or VAT number.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "results": { "type": "array", "description": "Up to 50 results, alphabetical by display name. Merged-away (duplicate) records are never returned.", "items": { "type": "object", "properties": { "record_id": { "type": "integer", "description": "This record's own id \u2014 use it for GET /registry/{record_id}." }, "display_number": { "type": "string", "description": "Zero-padded 5-digit display form of `record_id`." }, "name": { "type": "string", "description": "Composite display name." }, "type": { "type": "string", "enum": [ "person", "structure" ] }, "is_internal": { "type": "boolean", "description": "Whether this record is linked to a real system user/structure." }, "system_id": { "type": "string", "nullable": true, "description": "The linked system id, when `is_internal` is true." }, "is_aligned": { "type": "boolean", "nullable": true, "description": "For an internal record: whether its own structure/responsible assignment currently matches one of its real system role contexts (department membership/leadership). Null for an external record \u2014 the concept doesn't apply." } } } } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "post": { "summary": "Create a new EXTERNAL Registry record", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "person", "structure" ] }, "first_name": { "type": "string", "description": "Required for type=person." }, "last_name": { "type": "string", "description": "Required for type=person." }, "name": { "type": "string", "description": "Required for type=structure \u2014 the structure's own name." }, "sex": { "type": "string" }, "birth_date": { "type": "string", "description": "YYYY-MM-DD. Person only." }, "birth_city": { "type": "string" }, "birth_province": { "type": "string" }, "birth_state": { "type": "string" }, "citizenship": { "type": "string" }, "role": { "type": "string", "description": "Person only \u2014 their role/title." }, "structure_record_id": { "type": "integer", "nullable": true, "description": "Person only \u2014 their membership structure, a real registry record id." }, "responsible_record_id": { "type": "integer", "nullable": true, "description": "Structure only \u2014 its own responsible person, a real registry record id." }, "taxcode": { "type": "string" }, "vat_number": { "type": "string" }, "email": { "type": "string" }, "pec": { "type": "string" }, "website": { "type": "string" }, "phone_number": { "type": "string" }, "mobile_number": { "type": "string" }, "fax_number": { "type": "string" }, "home_address": { "type": "string" }, "home_city": { "type": "string" }, "home_district": { "type": "string" }, "home_country": { "type": "string" }, "home_postcode": { "type": "string" }, "note": { "type": "string" } }, "required": [ "type" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "type": "object", "description": "The newly-created record, same shape as one row of GET /registry's own results." } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/registry/{id}": { "get": { "summary": "Get a Registry record \u2014 full profile", "security": [ { "UserKey": [] } ], "x-status": "enabled", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "record_id": { "type": "integer", "description": "This record's own id." }, "name": { "type": "string", "description": "Composite display name." }, "type": { "type": "string", "enum": [ "person", "structure" ] }, "is_internal": { "type": "boolean", "description": "Whether linked to a real system user/structure." }, "linked_uid": { "type": "integer", "nullable": true, "description": "The linked system user's own login id, when resolvable." }, "structure": { "type": "object", "description": "This record's own structure assignment.", "properties": { "record_id": { "type": "integer", "nullable": true }, "display": { "type": "string", "nullable": true } } }, "responsible": { "type": "object", "description": "This record's own responsible-person assignment.", "properties": { "record_id": { "type": "integer", "nullable": true }, "display": { "type": "string", "nullable": true } } }, "contexts": { "type": "array", "description": "Real system role contexts (Founder/Area Manager/Dept. Leader/Employee) for an internal person \u2014 empty for a structure or an external/unlinked person.", "items": { "type": "object", "properties": { "role": { "type": "string" }, "department_label": { "type": "string" }, "reports_to": { "type": "object", "properties": { "status": { "type": "string" }, "record_id": { "type": "integer", "nullable": true }, "label": { "type": "string" } } }, "active": { "type": "boolean", "description": "Whether this specific context matches this record's own current structure/responsible assignment." } } } }, "is_aligned": { "type": "boolean", "description": "Whether the structure/responsible assignment above currently matches a real system role context." }, "merged_survivor": { "type": "object", "nullable": true, "description": "If this record was merged into another (duplicate-merging isn't migrated here), the surviving record to redirect to. This record itself always stays resolvable \u2014 historical references must keep working." }, "mismatches": { "type": "array", "description": "Fields that differ between this registry record and its linked system user, for `POST /registry/{id}/sync`. Empty when not internal, or when there's nothing to sync.", "items": { "type": "object", "properties": { "field": { "type": "string" }, "registry_value": { "type": "string", "nullable": true }, "system_value": { "type": "string", "nullable": true }, "suggested_direction": { "type": "string", "enum": [ "to_registry", "to_system" ] } } } }, "can": { "type": "object", "description": "Your real edit/sync permission for THIS record \u2014 `edit`/`sync` booleans." } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "patch": { "summary": "Edit a Registry record", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "name": { "type": "string", "description": "For a structure record (`type: \"structure\"`) only \u2014 its own single display name field." }, "taxcode": { "type": "string" }, "vat_number": { "type": "string" }, "sex": { "type": "string" }, "citizenship": { "type": "string" }, "citizenship_other": { "type": "string" }, "birth_date": { "type": "string", "description": "YYYY-MM-DD, or null to clear." }, "birth_city": { "type": "string" }, "birth_province": { "type": "string" }, "birth_state": { "type": "string" }, "home_address": { "type": "string" }, "home_number": { "type": "string" }, "home_postcode": { "type": "string" }, "home_city": { "type": "string" }, "home_district": { "type": "string" }, "home_country": { "type": "string" }, "home_co": { "type": "string", "description": "Care-of / attention-line, for the home address." }, "home_date": { "type": "string", "description": "YYYY-MM-DD, or null to clear." }, "mobile_number": { "type": "string" }, "phone_number": { "type": "string" }, "fax_number": { "type": "string" }, "email": { "type": "string" }, "pec": { "type": "string", "description": "Certified email (PEC), an Italian legal-mail concept \u2014 a real, distinct field from `email`." }, "note": { "type": "string" }, "structure_record_id": { "type": "integer", "description": "Sets this record's own structure assignment \u2014 pass another registry record's id (or a resolvable system id), or null to clear." }, "responsible_record_id": { "type": "integer", "description": "Sets this record's own responsible-person assignment, same resolution as `structure_record_id`." } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/registry/{id}/sync": { "post": { "summary": "Apply a Registry <-> system-user field sync", "security": [ { "UserKey": [] } ], "x-status": "enabled", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "description": "Each entry: `{field, direction}` \u2014 `field` is one of the names from `GET /registry/{id}`'s own `mismatches`, `direction` is `to_registry` (system user -> registry) or `to_system` (registry -> system user).", "items": { "type": "object" } } }, "required": [ "fields" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-search": { "get": { "summary": "Unified Protocol document search", "security": [ { "UserKey": [] } ], "x-status": "enabled", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Defaults to `global` (every box you have visibility into). A specific type 403s if you lack that box's own view permission.", "schema": { "type": "string", "enum": [ "global", "arrival", "departure", "internal", "register" ] } }, { "name": "q", "in": "query", "required": false, "description": "Substring/regex match against subject, classification, notes, keywords, attachment filenames, means of transmission, external protocol reference, and sender/recipient name or email.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Defaults to `active` (everything except cancelled).", "schema": { "type": "string", "enum": [ "active", "cancelled", "returned", "all" ] } }, { "name": "date_from", "in": "query", "required": false, "description": "YYYY-MM-DD, inclusive.", "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "required": false, "description": "YYYY-MM-DD, inclusive.", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Matches either the registration year or the original (imported) document year.", "schema": { "type": "integer" } }, { "name": "classification", "in": "query", "required": false, "description": "Substring/regex match against the classification `var`.", "schema": { "type": "string" } }, { "name": "dep", "in": "query", "required": false, "description": "A structure acronym \u2014 matches either the posting or the owning (RPA) department.", "schema": { "type": "string" } }, { "name": "role", "in": "query", "required": false, "description": "Documents where you are the RPA (`mine_rpa`), where you personally appear in the CC list (`mine_cc`), where one of your OWN structures appears in the CC list (`uor_cc`), or that you authored (`mine_author`) \u2014 mirrors the Dashboard widget's own 4 personal-tab links.", "schema": { "type": "string", "enum": [ "mine_rpa", "mine_cc", "uor_cc", "mine_author" ] } }, { "name": "in_folder", "in": "query", "required": false, "description": "Whether the document has already been placed into a folder. Mirrors the Dashboard's own \"to be filed\" stat when combined with `role=mine_rpa`.", "schema": { "type": "string", "enum": [ "yes", "no" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "type": { "type": "string", "description": "The resolved search type (never `global` unresolved \u2014 reflects what was actually queried)." }, "results": { "type": "array", "description": "Up to 100 results, newest first.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Use this with `GET /protocol-documents/{id}`." }, "box": { "type": "string", "enum": [ "arrivo", "uscita", "interno" ], "description": "The document's own type." }, "display_number": { "type": "string", "nullable": true, "description": "Protocol number, or register number when registered but not yet protocol-numbered. Null for a register-only entry with neither yet." }, "date": { "type": "string", "description": "MySQL datetime." }, "subject": { "type": "string" }, "status": { "type": "integer", "description": "Raw status code (-1 cancelled, 3 returned, others active/workflow states)." }, "status_label": { "type": "string", "enum": [ "Active", "Cancelled", "Returned" ] }, "classification": { "type": "string", "nullable": true, "description": "The classification `var` \u2014 resolve a real label via `GET /reference/protocol-classifications`." }, "is_register": { "type": "boolean", "description": "Whether this document also has a register entry." } } } } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-uop-inbox": { "get": { "summary": "List the UOP (Protocol Office) incoming-mail inbox", "security": [ { "UserKey": [] } ], "x-status": "enabled", "parameters": [ { "name": "view", "in": "query", "required": false, "description": "Defaults to `pending` (not yet triaged).", "schema": { "type": "string", "enum": [ "pending", "history", "spam" ] } }, { "name": "q", "in": "query", "required": false, "description": "Substring match against sender, subject, or body.", "schema": { "type": "string" } }, { "name": "mailbox", "in": "query", "required": false, "description": "Exact match against one of `mailboxes`' own `value`.", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "required": false, "description": "YYYY-MM-DD, inclusive.", "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "required": false, "description": "YYYY-MM-DD, inclusive.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "25 per page, defaults to 1.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "view": { "type": "string", "description": "The resolved tab." }, "tab_counts": { "type": "object", "description": "Pending/history/spam counts, always for ALL tabs regardless of `view`.", "properties": { "pending": { "type": "integer" }, "history": { "type": "integer" }, "spam": { "type": "integer" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Use this with GET /protocol-uop-inbox/{id}." }, "sender": { "type": "string" }, "subject": { "type": "string" }, "received_at": { "type": "string", "description": "MySQL datetime." }, "mailbox": { "type": "string", "nullable": true, "description": "The receiving mailbox's own display label, falling back to its raw address." }, "linked_doc_id": { "type": "integer", "nullable": true, "description": "Set once this email has already been registered as a Protocol document \u2014 use with GET /protocol-documents/{id}." }, "linked_prot_id": { "type": "string", "nullable": true, "description": "The linked document's own protocol number, when set." } } } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "total_pages": { "type": "integer" }, "mailboxes": { "type": "array", "description": "Every mailbox this brand has ever received into, for the `mailbox` filter.", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } } } } } }, "error": { "type": "object", "nullable": true } } } } } }, "default": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "data": { "type": "object", "nullable": true }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/protocol-uop-inbox/{id}": { "get": { "summary": "Preview one UOP inbox email", "security": [ { "UserKey": [] } ], "x-status": "enabled", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "sender": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string", "description": "Raw email HTML body, with `