CVE data is to be in the JSON 5.2 CVE Record format. Details of the JSON 5.2 schema are located here.
Contact the CVE Services team", "contact": { "name": "CVE Services Overview", "url": "https://www.cve.org/AllResources/CveServices" } }, "servers": [ { "url": "/api" } ], "tags": [ { "name": "CVE ID" }, { "name": "CVE Record" }, { "name": "Data Registry — Organizations", "description": "Organization records, CVE ID quotas, hierarchy, and Data Registry workflows under `/registry/org`. Organization updates use JSON request bodies and can involve joint approval. See Legacy — Organizations for the older endpoints. Compare request schemas and access rules when switching between them." }, { "name": "Data Registry — Users", "description": "User accounts and roles under `/registry/org/{shortname}/...` and `/registry/users`. Profile updates use JSON request bodies; dedicated endpoints grant and revoke roles. See Legacy — Users for the older endpoints, which use different user schemas." }, { "name": "Utilities" }, { "name": "Conversation" }, { "name": "Review Object" }, { "name": "Notification" }, { "name": "Audit" }, { "name": "Glossary" }, { "name": "Legacy — Organizations", "description": "Older organization endpoints under `/org`, using legacy organization schemas and query parameters for updates. See Data Registry — Organizations for the newer endpoints, which have different request schemas, access rules, and approval behavior." }, { "name": "Legacy — Users", "description": "Older user endpoints under `/org/{shortname}/...` and `/users`, using legacy user schemas and query parameters for profile updates. See Data Registry — Users for the newer endpoints and dedicated role management operations." } ], "paths": { "/cve-id": { "get": { "tags": [ "CVE ID" ], "summary": "Retrieves information about CVE IDs after applying the query parameters as filters (accessible to registered users, Secretariat, and Bulk Download)", "description": "Registered users can access this endpoint. Secretariat and Bulk Download organizations can retrieve CVE IDs across organizations; other users are limited to CVE IDs owned by their own organization.
Regular, CNA & Admin Users: Retrieves filtered CVE IDs owned by the user's organization
Secretariat: Retrieves filtered CVE IDs owned by any organization
Bulk Download: Retrieves filtered CVE IDs owned by any organization with owner and requester details redacted
", "operationId": "cveIdGetFiltered", "parameters": [ { "$ref": "#/components/parameters/cveIdGetFilteredState" }, { "$ref": "#/components/parameters/cveIdGetFilteredCveIdYear" }, { "$ref": "#/components/parameters/cveIdGetFilteredTimeReservedLt" }, { "$ref": "#/components/parameters/cveIdGetFilteredTimeReservedGt" }, { "$ref": "#/components/parameters/cveIdGetFilteredTimeModifiedLt" }, { "$ref": "#/components/parameters/cveIdGetFilteredTimeModifiedGt" }, { "$ref": "#/components/parameters/pageQuery" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "A filtered list of information about CVE IDs owned by the organization, along with pagination fields if results span multiple pages of data", "content": { "application/json": { "schema": { "$ref": "../schemas/cve-id/list-cve-ids-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } }, "post": { "tags": [ "CVE ID" ], "summary": "Reserves CVE IDs for the organization provided in the short_name query parameter (accessible to CNAs and Secretariat)", "description": "User must belong to an organization with the CNA or Secretariat role
CNA: Reserves CVE IDs for the CNA
Secretariat: Reserves CVE IDs for any organization
", "operationId": "cveIdReserve", "parameters": [ { "$ref": "#/components/parameters/amount" }, { "$ref": "#/components/parameters/batch_type" }, { "$ref": "#/components/parameters/cve_year" }, { "$ref": "#/components/parameters/short_name" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "A list of the newly reserved CVE IDs", "content": { "application/json": { "schema": { "$ref": "../schemas/cve-id/create-cve-ids-response.json" } } } }, "206": { "description": "A partial list of the CVE IDs the IDR service managed to reserve before encountering a case where no more CVE IDs could be reserved", "content": { "application/json": { "schema": { "$ref": "../schemas/cve-id/create-cve-ids-partial-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/cve-id/{id}": { "get": { "tags": [ "CVE ID" ], "summary": "Retrieves information about the specified CVE ID (accessible to all users)", "description": "Endpoint is accessible to all
Regular, CNA & Admin Users: Retrieves full information about a CVE ID owned by their organization; partial information about a CVE ID owned by other organizations
Unauthenticated Users: Retrieves partial information about a CVE ID
Secretariat: Retrieves full information about a CVE ID owned by any organization
Note - The owning organization of RESERVED CVE IDs is redacted for all users other than those in the owning organization or Secretariat
", "operationId": "cveIdGetSingle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The id of the CVE ID information to retrieve" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "The requested CVE ID information is returned", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Indicates the service limit associated with the client in the current time window. If the client exceeds that limit, it MAY not be served." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "Indicates a service policy currently associated with the client. Its value is informative." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Indicates the remaining quota units associated with the expiring-limit. Clients MUST NOT assume that a positive remaining value is a guarantee that further requests will be served. When the value of the remaining keyword is low, it indicates that the server may soon throttle the client." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Indicates the number of seconds until the available quota units associated with the expiring-limit resets." } }, "content": { "application/json": { "schema": { "$ref": "../schemas/cve-id/get-cve-id-response.json" } } } }, "400": { "description": "Bad Request", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Indicates the service limit associated with the client in the current time window. If the client exceeds that limit, it MAY not be served." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "Indicates a service policy currently associated with the client. Its value is informative." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Indicates the remaining quota units associated with the expiring-limit. Clients MUST NOT assume that a positive remaining value is a guarantee that further requests will be served. When the value of the remaining keyword is low, it indicates that the server may soon throttle the client." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Indicates the number of seconds until the available quota units associated with the expiring-limit resets." } }, "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Indicates the service limit associated with the client in the current time window. If the client exceeds that limit, it MAY not be served." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "Indicates a service policy currently associated with the client. Its value is informative." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Indicates the remaining quota units associated with the expiring-limit. Clients MUST NOT assume that a positive remaining value is a guarantee that further requests will be served. When the value of the remaining keyword is low, it indicates that the server may soon throttle the client." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Indicates the number of seconds until the available quota units associated with the expiring-limit resets." } }, "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Indicates the service limit associated with the client in the current time window. If the client exceeds that limit, it MAY not be served." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "Indicates a service policy currently associated with the client. Its value is informative." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Indicates the remaining quota units associated with the expiring-limit. Clients MUST NOT assume that a positive remaining value is a guarantee that further requests will be served. When the value of the remaining keyword is low, it indicates that the server may soon throttle the client." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Indicates the number of seconds until the available quota units associated with the expiring-limit resets." } }, "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Indicates the service limit associated with the client in the current time window. If the client exceeds that limit, it MAY not be served." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "Indicates a service policy currently associated with the client. Its value is informative." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Indicates the remaining quota units associated with the expiring-limit. Clients MUST NOT assume that a positive remaining value is a guarantee that further requests will be served. When the value of the remaining keyword is low, it indicates that the server may soon throttle the client." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Indicates the number of seconds until the available quota units associated with the expiring-limit resets." } }, "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Indicates the service limit associated with the client in the current time window. If the client exceeds that limit, it MAY not be served." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "Indicates a service policy currently associated with the client. Its value is informative." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Indicates the remaining quota units associated with the expiring-limit. Clients MUST NOT assume that a positive remaining value is a guarantee that further requests will be served. When the value of the remaining keyword is low, it indicates that the server may soon throttle the client." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Indicates the number of seconds until the available quota units associated with the expiring-limit resets." } }, "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Indicates the service limit associated with the client in the current time window. If the client exceeds that limit, it MAY not be served." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "Indicates a service policy currently associated with the client. Its value is informative." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Indicates the remaining quota units associated with the expiring-limit. Clients MUST NOT assume that a positive remaining value is a guarantee that further requests will be served. When the value of the remaining keyword is low, it indicates that the server may soon throttle the client." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Indicates the number of seconds until the available quota units associated with the expiring-limit resets." } }, "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } }, "put": { "tags": [ "CVE ID" ], "summary": "Updates information related to the specified CVE ID (accessible to CNAs and Secretariat)", "description": "User must belong to an organization with the CNA or Secretariat role
CNA: Updates information related to a CVE ID owned by the CNA
Secretariat: Updates a CVE ID owned by any organization
", "operationId": "cveIdUpdateSingle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The id of the CVE ID to update" }, { "$ref": "#/components/parameters/org" }, { "$ref": "#/components/parameters/state" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "The updated CVE ID information is returned", "content": { "application/json": { "schema": { "$ref": "../schemas/cve-id/update-cve-id-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/cve-id-range/{year}": { "post": { "tags": [ "CVE ID" ], "summary": "Creates a CVE-ID-Range for the specified year (accessible to Secretariat)", "description": "User must belong to an organization with the Secretariat role
Secretariat: Explicitly creates a CVE-ID-Range for the specified year, including past years or future years outside the automatic activation window. Returns 200 with no response body when created. If the range already exists, returns 400 YEAR_RANGE_EXISTS and preserves its allocation counters.
During POST /api/cve-id, an eligible reservation request automatically creates a missing range before allocating IDs. This applies to priority (single-ID), sequential, and non-sequential reservations, subject to the usual authorization and quota checks.
Activation happens on demand when a reservation request reaches the allocation step. If a range is missing and the year is outside the automatic activation window, the reservation request returns 403 CANNOT_RESERVE_FOR_YEAR.
Once a range exists, reservations use it without applying the automatic activation window again, including for past years, subject to the normal reservation limits.
", "operationId": "cveIdRangeCreate", "parameters": [ { "name": "year", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The year of the CVE-ID-Range" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "The CVE-ID-Range was created" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/cve/{id}": { "get": { "tags": [ "CVE Record" ], "summary": "Returns a CVE Record by CVE ID (accessible to all users)", "description": "Endpoint is accessible to all
All users: Retrieves the CVE Record specified
", "operationId": "cveGetSingle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The CVE ID for the Record to be retrieved" } ], "responses": { "200": { "description": "The requested published or rejected CVE Record", "content": { "application/json": { "schema": { "$ref": "../schemas/cve/get-cve-record-response.json" }, "examples": { "Published Record": { "$ref": "#/components/examples/publishedRecord" }, "Rejected Record": { "$ref": "#/components/examples/rejectedRecord" } } } } }, "400": { "description": "Bad Request", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Indicates the service limit associated with the client in the current time window. If the client exceeds that limit, it MAY not be served." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "Indicates a service policy currently associated with the client. Its value is informative." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Indicates the remaining quota units associated with the expiring-limit. Clients MUST NOT assume that a positive remaining value is a guarantee that further requests will be served. When the value of the remaining keyword is low, it indicates that the server may soon throttle the client." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Indicates the number of seconds until the available quota units associated with the expiring-limit resets." } }, "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "403": { "description": "Forbidden", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Indicates the service limit associated with the client in the current time window. If the client exceeds that limit, it MAY not be served." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "Indicates a service policy currently associated with the client. Its value is informative." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Indicates the remaining quota units associated with the expiring-limit. Clients MUST NOT assume that a positive remaining value is a guarantee that further requests will be served. When the value of the remaining keyword is low, it indicates that the server may soon throttle the client." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Indicates the number of seconds until the available quota units associated with the expiring-limit resets." } }, "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "429": { "description": "Too Many Requests", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Indicates the service limit associated with the client in the current time window. If the client exceeds that limit, it MAY not be served." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "Indicates a service policy currently associated with the client. Its value is informative." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Indicates the remaining quota units associated with the expiring-limit. Clients MUST NOT assume that a positive remaining value is a guarantee that further requests will be served. When the value of the remaining keyword is low, it indicates that the server may soon throttle the client." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Indicates the number of seconds until the available quota units associated with the expiring-limit resets." } }, "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Indicates the service limit associated with the client in the current time window. If the client exceeds that limit, it MAY not be served." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "Indicates a service policy currently associated with the client. Its value is informative." }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Indicates the remaining quota units associated with the expiring-limit. Clients MUST NOT assume that a positive remaining value is a guarantee that further requests will be served. When the value of the remaining keyword is low, it indicates that the server may soon throttle the client." }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Indicates the number of seconds until the available quota units associated with the expiring-limit resets." } }, "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } }, "post": { "tags": [ "CVE Record" ], "summary": "Creates a CVE Record from full CVE Record JSON for the specified ID (accessible to Secretariat.)", "description": "User must belong to an organization with the Secretariat role
Secretariat: Creates a CVE Record for any organization
", "operationId": "cveSubmit", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The CVE ID for the record being submitted" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "The CVE Record created", "content": { "application/json": { "schema": { "$ref": "../schemas/cve/create-cve-record-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "../schemas/cve/create-cve-record-secretariat-request.json" } } } } }, "put": { "tags": [ "CVE Record" ], "summary": "Updates a CVE Record from full CVE Record JSON for the specified ID (accessible to Secretariat.)", "description": "User must belong to an organization with the Secretariat role
Secretariat: Updates a CVE Record for any organization
", "operationId": "cveUpdateSingle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The CVE ID for the record being updated" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "The updated CVE Record", "content": { "application/json": { "schema": { "$ref": "../schemas/cve/update-full-cve-record-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "../schemas/cve/create-cve-record-secretariat-request.json" } } } } } }, "/cve": { "get": { "tags": [ "CVE Record" ], "summary": "Retrieves all CVE Records after applying the query parameters as filters (accessible to Secretariat or Bulk Download)", "description": "User must belong to an organization with the Secretariat or Bulk Download role
Secretariat and Bulk Download: Retrieves all CVE records for all organizations
", "operationId": "cveGetFiltered", "parameters": [ { "$ref": "#/components/parameters/cveRecordFilteredTimeModifiedLt" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" }, { "$ref": "#/components/parameters/cveRecordFilteredTimeModifiedGt" }, { "$ref": "#/components/parameters/cveRecordFilteredTimeCreatedLt" }, { "$ref": "#/components/parameters/cveRecordFilteredTimeCreatedGt" }, { "$ref": "#/components/parameters/cveState" }, { "$ref": "#/components/parameters/countOnly" }, { "$ref": "#/components/parameters/assignerShortName" }, { "$ref": "#/components/parameters/assigner" }, { "$ref": "#/components/parameters/pageQuery" }, { "$ref": "#/components/parameters/cnaModified" }, { "$ref": "#/components/parameters/adpShortName" } ], "responses": { "200": { "description": "Filtered CVE Records, or { totalCount } when count_only is true", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "../schemas/cve/list-cve-records-response.json" }, { "$ref": "../schemas/cve/get-cve-record-count.json" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/cve_count": { "get": { "tags": [ "CVE Record" ], "summary": "Retrieves the count of all the CVE Records after applying the query parameters as filters (accessible to all users)", "description": "Endpoint is accessible to all
Retrieves the count of all CVE records for all organizations
", "operationId": "cveGetFilteredCount", "parameters": [ { "$ref": "#/components/parameters/cveState" } ], "responses": { "200": { "description": "A count of the total number of filtered CVE records", "content": { "application/json": { "schema": { "$ref": "../schemas/cve/get-cve-record-count.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/cve_cursor": { "get": { "tags": [ "CVE Record" ], "summary": "Retrieves all CVE Records after applying the query parameters as filters. Uses cursor pagination to paginate results (accessible to Secretariat or Bulk Download)", "description": "User must belong to an organization with the Secretariat or Bulk Download role
Secretariat and Bulk Download: Retrieves all CVE records for all organizations
", "operationId": "cveGetFilteredCursor", "parameters": [ { "$ref": "#/components/parameters/cveRecordFilteredTimeModifiedLt" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" }, { "$ref": "#/components/parameters/cveRecordFilteredTimeModifiedGt" }, { "$ref": "#/components/parameters/cveState" }, { "$ref": "#/components/parameters/countOnly" }, { "$ref": "#/components/parameters/assignerShortName" }, { "$ref": "#/components/parameters/assigner" }, { "$ref": "#/components/parameters/cnaModified" }, { "$ref": "#/components/parameters/adpShortName" }, { "$ref": "#/components/parameters/nextPage" }, { "$ref": "#/components/parameters/previousPage" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "description": "Filtered CVE Records, or { totalCount } when count_only is true", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "../schemas/cve/cursor-cve-records-response.json" }, { "$ref": "../schemas/cve/get-cve-record-count.json" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/cve/{id}/cna": { "post": { "tags": [ "CVE Record" ], "summary": "Creates a CVE Record from CNA Container JSON for the specified ID (accessible to CNAs and Secretariat)", "description": "User must belong to an organization with the CNA or Secretariat role
CNA: Creates CVE Record for a CVE ID owned by their organization
Secretariat: Creates CVE Record for CVE IDs owned by any organization
", "operationId": "cveCnaCreateSingle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The CVE ID for the record being created" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" }, { "$ref": "#/components/parameters/erlCheck" } ], "responses": { "200": { "description": "The CVE Record created", "content": { "application/json": { "schema": { "$ref": "../schemas/cve/create-cve-record-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "description": "User must belong to an organization with the CNA or Secretariat role
CNA: Updates a CVE Record for records that are owned by their organization
Secretariat: Updates a CVE Record for records that are owned by any organization
", "operationId": "cveCnaUpdateSingle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The CVE ID for which the record is being updated" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" }, { "$ref": "#/components/parameters/erlCheck" } ], "responses": { "200": { "description": "The updated CVE Record", "content": { "application/json": { "schema": { "$ref": "../schemas/cve/update-full-cve-record-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "description": "User must belong to an organization with the CNA or Secretariat role
CNA: Creates a rejected CVE Record for a record owned by their organization
Secretariat: Creates a rejected CVE Record for a record owned by any organization
", "operationId": "cveCnaCreateReject", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The CVE ID for the record being rejected" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "The rejected CVE Record", "content": { "application/json": { "schema": { "$ref": "../schemas/cve/create-cve-record-rejection-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "description": "User must belong to an organization with the CNA or Secretariat role
CNA: Updates a rejected CVE Record for a record owned by their organization
Secretariat: Updates a rejected CVE Record for a record owned by any organization
", "operationId": "cveCnaUpdateReject", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The CVE ID for the record being rejected" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "The rejected CVE Record", "content": { "application/json": { "schema": { "$ref": "../schemas/cve/update-cve-record-rejection-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "description": "User must belong to an organization with the ADP or Secretariat role
ADP: Updates a CVE Record for records that are owned by any organization
Secretariat: Updates a CVE Record for records that are owned by any organization
", "operationId": "cveAdpUpdateSingle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The CVE ID for which the record is being updated" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "The updated CVE Record", "content": { "application/json": { "schema": { "$ref": "../schemas/cve/update-full-cve-record-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "description": "Note: providerMetadata is set by the server. If provided, it will be overwritten.", "required": true, "content": { "application/json": { "schema": { "$ref": "../schemas/cve/create-adp-record-adp-request.json" } } } } } }, "/org": { "get": { "tags": [ "Legacy — Organizations" ], "summary": "Retrieves all organizations (accessible to Secretariat)", "description": "Related Data Registry endpoint: GET /registry/org. Legacy responses use name and authority.active_roles; Data Registry responses use long_name and an authority array.
User must belong to an organization with the Secretariat role
Secretariat: Retrieves information about all organizations
", "operationId": "orgAll", "parameters": [ { "$ref": "#/components/parameters/pageQuery" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns information about all organizations, along with pagination fields if results span multiple pages of data", "content": { "application/json": { "schema": { "$ref": "../schemas/org/list-orgs-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } }, "post": { "tags": [ "Legacy — Organizations" ], "summary": "Creates an organization as specified in the request body (accessible to Secretariat)", "description": "Related Data Registry endpoint: POST /registry/org. The legacy request uses name and authority.active_roles; the Data Registry request uses long_name and an authority array.
User must belong to an organization with the Secretariat role
Secretariat: Creates an organization
Organizations whose only role is ROOT have an ID quota of zero, even when a positive quota is supplied.
", "operationId": "orgCreateSingle", "parameters": [ { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns information about the organization created", "content": { "application/json": { "schema": { "$ref": "../schemas/org/create-org-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "../schemas/org/create-org-request.json" } } } } } }, "/org/{shortname}": { "get": { "tags": [ "Legacy — Organizations" ], "summary": "Retrieves information about the organization specified by short name or UUID (accessible to same-organization users or Secretariat)", "description": "Related Data Registry endpoint: GET /registry. Legacy responses use name and authority.active_roles; Data Registry responses use long_name and an authority array.
Authenticated users can access this endpoint only for their own organization. Secretariat users can access any organization.
Regular, CNA & Admin Users: Retrieves organization record for the specified shortname or UUID if it is the user's organization
Secretariat: Retrieves information about any organization
", "operationId": "orgSingle", "parameters": [ { "name": "shortname", "in": "path", "required": true, "description": "The organization short name or UUID", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the organization information", "content": { "application/json": { "schema": { "$ref": "../schemas/org/get-org-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } }, "put": { "tags": [ "Legacy — Organizations" ], "summary": "Updates information about the organization specified by short name (accessible to Secretariat)", "description": "Related Data Registry endpoint: PUT /registry/org/{shortname}. This endpoint accepts updates through query parameters and requires Secretariat access. Data Registry updates use a JSON request body and also allow organization admins to request changes, with joint approval for designated fields.
User must belong to an organization with the Secretariat role
Secretariat: Updates any organization's information
Users cannot remove SECRETARIAT authority from their own organization. Another Secretariat organization must perform the demotion. Self-demotion returns 403 SECRETARIAT_CANNOT_SELF_DEMOTE.
Organizations whose only role is ROOT have an ID quota of zero. A supplied positive quota is normalized to zero, including when changing the organization's role to ROOT.
", "operationId": "orgUpdateSingle", "parameters": [ { "name": "shortname", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the organization" }, { "$ref": "#/components/parameters/id_quota" }, { "$ref": "#/components/parameters/name" }, { "$ref": "#/components/parameters/newShortname" }, { "$ref": "#/components/parameters/active_roles_add" }, { "$ref": "#/components/parameters/active_roles_remove" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns information about the organization updated", "content": { "application/json": { "schema": { "$ref": "../schemas/org/update-org-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/org/{shortname}/id_quota": { "get": { "tags": [ "Legacy — Organizations" ], "summary": "Retrieves an organization's CVE ID quota (accessible to same-organization users or Secretariat)", "description": "Related Data Registry endpoint: GET /registry/org/{shortname}/id_quota.
Authenticated users can access this endpoint only for their own organization. Secretariat users can access any organization.
Regular, CNA & Admin Users: Retrieves the CVE ID quota for the user's organization
Secretariat: Retrieves the CVE ID quota for any organization
", "operationId": "orgIdQuota", "parameters": [ { "name": "shortname", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the organization" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the CVE ID quota for an organization", "content": { "application/json": { "schema": { "$ref": "../schemas/org/get-org-quota-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/org/{shortname}/users": { "get": { "tags": [ "Legacy — Users" ], "summary": "Retrieves all users for the organization with the specified short name (accessible to same-organization users or Secretariat)", "description": "Related Data Registry endpoint: GET /registry/org/{shortname}/users. Legacy responses expose active and authority.active_roles; Data Registry responses expose status and role.
Authenticated users can access this endpoint only for their own organization. Secretariat users can access any organization.
Regular, CNA & Admin Users: Retrieves information about users in the same organization
Secretariat: Retrieves all user information for any organization
", "operationId": "userOrgAll", "parameters": [ { "name": "shortname", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the organization" }, { "$ref": "#/components/parameters/pageQuery" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns all users for the organization, along with pagination fields if results span multiple pages of data", "content": { "application/json": { "schema": { "$ref": "../schemas/user/list-users-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/org/{shortname}/user": { "post": { "tags": [ "Legacy — Users" ], "summary": "Create a user with the provided short name as the owning organization (accessible to Secretariat or target organization Admin)", "description": "Related Data Registry endpoint: POST /registry/org/{shortname}/user. Uses the legacy user request schema. The Data Registry request requires a status field.
User must belong to an organization with the Secretariat role or be an Admin of the target organization
Admin User: Creates a user for the Admin's organization
Secretariat: Creates a user for any organization
", "operationId": "userCreateSingle", "parameters": [ { "name": "shortname", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the organization" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the new user information (with the secret)", "content": { "application/json": { "schema": { "$ref": "../schemas/user/create-user-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "../schemas/user/create-user-request.json" } } } } } }, "/org/{shortname}/user/{username}": { "get": { "tags": [ "Legacy — Users" ], "summary": "Retrieves information about a user for the specified username and organization short name (accessible to same-organization users or Secretariat)", "description": "Related Data Registry endpoint: GET /registry/org/{shortname}/user/{username}. Legacy responses expose active and authority.active_roles; Data Registry responses expose status and role.
Authenticated users can access this endpoint only for users in their own organization. Secretariat users can access any user.
Regular, CNA & Admin Users: Retrieves information about a user in the same organization
Secretariat: Retrieves any user's information
", "operationId": "userSingle", "parameters": [ { "name": "shortname", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the organization" }, { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The username of the user" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns information about the specified user", "content": { "application/json": { "schema": { "$ref": "../schemas/user/get-user-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } }, "put": { "tags": [ "Legacy — Users" ], "summary": "Updates information about a user for the specified username and organization shortname (accessible to self, same-organization Admins, or Secretariat)", "description": "Related Data Registry endpoint: PUT /registry/org/{shortname}/user/{username}. This endpoint accepts updates through query parameters. The Data Registry endpoint uses a JSON request body and the Data Registry user schema.
Authenticated users can update their own name fields. Organization admins can update users in their organization. Secretariat users can update users in any organization.
Regular User: Updates the user's own information. Only name fields may be changed.
Admin User: Updates information about a user in the Admin's organization. Allowed to change all fields except org_short_name.
Secretariat: Updates information about a user in any organization. Allowed to change all fields.
Deactivation preserves assigned ADMIN membership while preventing authentication. Legacy active_roles continues to show ADMIN while inactive if the assignment remains. Reactivation restores admin access without a separate role grant. Explicit revocation or an organization move removes ADMIN.
Moving a user to another organization removes ADMIN in both the source and destination. ADMIN requested in the move is not granted; promotion requires a separate authorized request after the move.
", "operationId": "userUpdateSingle", "parameters": [ { "name": "shortname", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the organization" }, { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The username of the user" }, { "$ref": "#/components/parameters/active" }, { "$ref": "#/components/parameters/activeUserRolesAdd" }, { "$ref": "#/components/parameters/activeUserRolesRemove" }, { "$ref": "#/components/parameters/nameFirst" }, { "$ref": "#/components/parameters/nameLast" }, { "$ref": "#/components/parameters/nameMiddle" }, { "$ref": "#/components/parameters/nameSuffix" }, { "$ref": "#/components/parameters/newUsername" }, { "$ref": "#/components/parameters/orgShortname" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the updated user information", "content": { "application/json": { "schema": { "$ref": "../schemas/user/update-user-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/org/{shortname}/user/{username}/reset_secret": { "put": { "tags": [ "Legacy — Users" ], "summary": "Reset the API key for a user (accessible to self, same-organization Admins, or Secretariat)", "description": "Related Data Registry endpoint: PUT /registry/org/{shortname}/user/{username}/reset_secret.
Authenticated users can reset their own API secret. Organization admins can reset users in their organization. Secretariat users can reset any user's API secret.
Regular User: Resets user's own API secret
Admin User: Resets any user's API secret in the Admin's organization
Secretariat: Resets any user's API secret
", "operationId": "userResetSecret", "parameters": [ { "name": "shortname", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the organization" }, { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The username of the user" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the new API key", "content": { "application/json": { "schema": { "$ref": "../schemas/user/reset-secret-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/users": { "get": { "tags": [ "Legacy — Users" ], "summary": "Retrieves information about all registered users (accessible to Secretariat)", "description": "Related Data Registry endpoint: GET /registry/users. Legacy responses expose active and authority.active_roles; Data Registry responses expose status and role.
User must belong to an organization with the Secretariat role
Secretariat: Retrieves information about all users for all organizations
", "operationId": "userAll", "parameters": [ { "$ref": "#/components/parameters/pageQuery" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns all users, along with pagination fields if results span multiple pages of data.", "content": { "application/json": { "schema": { "$ref": "../schemas/user/list-users-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/health-check": { "get": { "tags": [ "Utilities" ], "summary": "Checks that the system is running (accessible to all users)", "description": "Endpoint is accessible to all
Returns a 200 response code when CVE Services are running
", "operationId": "healthCheck", "responses": { "200": { "description": "Returns a 200 response code" } } } }, "/registry/org": { "get": { "tags": [ "Data Registry — Organizations" ], "summary": "Retrieves all registry organizations (accessible to Secretariat)", "description": "Related legacy endpoint: GET /org. Data Registry responses use long_name and an authority array; legacy responses use name and authority.active_roles.
User must belong to an organization with the Secretariat role
Secretariat: Retrieves information about all registry organizations
", "operationId": "registryOrgAll", "parameters": [ { "$ref": "#/components/parameters/pageQuery" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns information about all registry organizations, along with pagination fields if results span multiple pages of data", "content": { "application/json": { "schema": { "$ref": "../schemas/registry-org/list-registry-orgs-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } }, "post": { "tags": [ "Data Registry — Organizations" ], "summary": "Creates an organization (accessible to Secretariat)", "description": "Related legacy endpoint: POST /org. The Data Registry request uses long_name and an authority array; the legacy request uses name and authority.active_roles.
User must belong to an organization with the Secretariat role
Secretariat: Creates a new organization
Organizations whose only role is ROOT are created with an ID quota of zero. The ROOT request schema does not accept an id_quota field.
", "operationId": "registryOrgCreateSingle", "parameters": [ { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "The created registry organization and confirmation message", "content": { "application/json": { "schema": { "$ref": "../schemas/registry-org/create-registry-org-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "450": { "description": "Organization creation failed in the repository", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "../schemas/registry-org/create-registry-org-request.json" }, "example": { "short_name": "example_cna", "long_name": "Example CNA", "id_quota": 1000, "authority": [ "CNA" ] } } } } } }, "/registry/org-hierarchy": { "get": { "tags": [ "Data Registry — Organizations" ], "summary": "Retrieves the complete registry organization hierarchy (Secretariat only)", "description": "User must belong to an organization with the Secretariat role.
Returns an unpaginated array of organization trees. Each node contains UUID, short_name, long_name, authority, and children. ROOT nodes also contain is_top_level_root, and CNA nodes contain is_last_resort. Organizations without a parent appear at the top level, and leaves have an empty children array.
", "operationId": "registryOrgHierarchy", "parameters": [ { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the complete organization hierarchy with UUIDs, organization names, roles, role-specific flags, and nested children", "content": { "application/json": { "schema": { "$ref": "../schemas/registry-org/get-org-hierarchy-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/registry/org/cnas": { "get": { "tags": [ "Data Registry — Organizations" ], "summary": "Lists active CNAs in the CVE.org partner-list format (Secretariat only)", "description": "User must belong to an organization with the Secretariat role.
Secretariat: Retrieves the active CNA list built from registry organization data in the CVE.org partner-list format.
", "operationId": "registryOrgActiveCnas", "parameters": [ { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns active CNAs in the CVE.org partner-list format", "content": { "application/json": { "schema": { "$ref": "../schemas/registry-org/list-active-cnas-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/registry/org/{shortname}/users": { "get": { "tags": [ "Data Registry — Users" ], "summary": "Retrieves all users for the organization with the specified short name (accessible to same-organization users or Secretariat)", "description": "Related legacy endpoint: GET /org/{shortname}/users. Data Registry responses expose status and role; legacy responses expose active and authority.active_roles.
Authenticated users can access this endpoint only for their own organization. Secretariat users can access any organization.
Regular, CNA & Admin Users: Retrieves information about users in the same organization
Secretariat: Retrieves all user information for any organization
", "operationId": "registryOrgUsersAll", "parameters": [ { "name": "shortname", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the organization" }, { "$ref": "#/components/parameters/pageQuery" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns all users for the organization, along with pagination fields if results span multiple pages of data", "content": { "application/json": { "schema": { "$ref": "../schemas/registry-user/list-registry-users-response.json" }, "example": { "totalCount": 1, "itemsPerPage": 100, "pageCount": 1, "currentPage": 1, "prevPage": null, "nextPage": null, "users": [ { "UUID": "fe566221-6a2c-4279-8800-4d3795325997", "username": "jdoe", "name": { "first": "John", "last": "Doe" }, "role": "ADMIN", "status": "active", "created": "2021-02-12T17:15:37.382Z", "last_updated": "2021-02-12T17:15:37.382Z" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/registry/org/{shortname}/id_quota": { "get": { "tags": [ "Data Registry — Organizations" ], "summary": "Retrieves an organization's CVE ID quota (accessible to same-organization users or Secretariat)", "description": "Related legacy endpoint: GET /org/{shortname}/id_quota.
Authenticated users can access this endpoint only for their own organization. Secretariat users can access any organization.
Regular, CNA & Admin Users: Retrieves the CVE ID quota for the user's organization
Secretariat: Retrieves the CVE ID quota for any organization
", "operationId": "registryOrgIdQuota", "parameters": [ { "name": "shortname", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the organization" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the CVE ID quota for an organization", "content": { "application/json": { "schema": { "$ref": "../schemas/registry-org/get-registry-org-quota-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/registry/org/{shortname}": { "get": { "tags": [ "Data Registry — Organizations" ], "summary": "Retrieves information about the registry organization specified by short name or UUID (accessible to same-organization users or Secretariat)", "description": "Related legacy endpoint: GET /org/{shortname}. Data Registry responses use long_name and an authority array; legacy responses use name and authority.active_roles.
Authenticated users can access this endpoint only for their own organization. Secretariat users can access any organization.
Regular, CNA & Admin Users: Retrieves registry organization record for the specified shortname or UUID if it is the user's organization
Secretariat: Retrieves information about any registry organization
The reports_to, top_level_root, and oversees relationship fields contain organization short names.
The _hierarchy array contains the ancestor path from the top-level Root to the requested organization and that organization's complete subtree. Ancestors include only the child on that path. Nodes contain UUID, short_name, long_name, authority, and children. ROOT nodes also contain is_top_level_root, and CNA nodes contain is_last_resort. An organization without a parent begins its own tree.
", "operationId": "registryOrgSingle", "parameters": [ { "name": "expand", "in": "query", "description": "Optional expanded related data. Accepted value: users.", "required": false, "schema": { "type": "string", "enum": [ "users" ] } }, { "name": "shortname", "in": "path", "required": true, "description": "The organization short name or UUID", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the registry organization information", "content": { "application/json": { "schema": { "$ref": "../schemas/registry-org/get-registry-org-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } }, "put": { "tags": [ "Data Registry — Organizations" ], "summary": "Updates information about the organization specified by short name (accessible to Secretariat or same-organization Admin)", "description": "Related legacy endpoint: PUT /org/{shortname}. This endpoint accepts a JSON request body and allows organization admins to request changes, with joint approval for designated fields. The legacy endpoint uses query parameters and requires Secretariat access.
User must belong to an organization with the Secretariat role or be an Admin of the requested organization.
With Joint Approval required for the following fields:
Secretariat: Updates any organization's information
Users cannot remove SECRETARIAT authority from their own organization. Another Secretariat organization must perform the demotion. Self-demotion returns 403 SECRETARIAT_CANNOT_SELF_DEMOTE.
Organization Admin: Requests changes to its organization's information
Organizations whose only role is ROOT have an ID quota of zero. An approved change to ROOT resets the quota to zero, even when the request omits it.
User must belong to an organization with the Secretariat role
Secretariat: Deletes the specified registry organization
", "operationId": "registryOrgDeleteSingle", "parameters": [ { "name": "shortname", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the registry organization" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Confirms deletion of the registry organization", "content": { "application/json": { "schema": { "$ref": "../schemas/registry-org/delete-registry-org-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/registry/org/{shortname}/user/{username}": { "get": { "tags": [ "Data Registry — Users" ], "summary": "Retrieves information about a user for the specified username and organization short name (accessible to same-organization users or Secretariat)", "description": "Related legacy endpoint: GET /org/{shortname}/user/{username}. Data Registry responses expose status and role; legacy responses expose active and authority.active_roles.
Authenticated users can access this endpoint only for users in their own organization. Secretariat users can access any user.
Regular, CNA & Admin Users: Retrieves information about a registry user in the same organization
Secretariat: Retrieves any registry user's information
", "operationId": "registryUserSingle", "parameters": [ { "name": "shortname", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the organization" }, { "name": "username", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9._@-]+$" }, "description": "The username of the registry user" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns information about the specified registry user", "content": { "application/json": { "schema": { "$ref": "../schemas/registry-user/get-registry-user-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } }, "put": { "tags": [ "Data Registry — Users" ], "summary": "Updates information about a user for the specified username and organization shortname (accessible to self, same-organization Admins, or Secretariat)", "description": "Related legacy endpoint: PUT /org/{shortname}/user/{username}. This endpoint accepts updates through a JSON request body. The legacy endpoint uses query parameters and the legacy user schema.
Authenticated users can update their own name fields. Organization admins can update users in their organization. Secretariat users can update users in any organization.
Regular User: Updates the user's own information. Only name fields may be changed.
Admin User: Updates information about a user in the Admin's organization. Allowed to change all fields except org_short_name.
Secretariat: Updates information about a user in any organization. Allowed to change all fields.
Deactivation preserves assigned ADMIN membership while preventing authentication. Reactivation retains that assignment unless ADMIN was explicitly revoked or the user moved organizations. Omitting role from a profile update does not revoke ADMIN.
Moving a user to another organization removes ADMIN in both the source and destination. ADMIN requested in the move is not granted; promotion requires a separate authorized request after the move.
", "operationId": "registryUserUpdateSingle", "parameters": [ { "name": "shortname", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the organization" }, { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The username of the user" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the updated user information", "content": { "application/json": { "schema": { "$ref": "../schemas/registry-user/update-registry-user-response.json" }, "example": { "message": "jdoe was successfully updated.", "updated": { "UUID": "fe566221-6a2c-4279-8800-4d3795325997", "username": "jdoe", "name": { "first": "John", "last": "Doe" }, "status": "active", "created": "2021-02-12T17:15:37.382Z", "last_updated": "2021-02-12T17:15:37.382Z" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "../schemas/registry-user/update-registry-user-request.json" }, "example": { "username": "jdoe", "status": "active", "name": { "first": "John", "last": "Doe" } } } } } }, "delete": { "tags": [ "Data Registry — Users" ], "summary": "Deletes the registry user specified by organization and username (accessible to Secretariat only)", "description": "User must belong to an organization with the Secretariat role
Secretariat: Deletes the specified user from the specified organization
", "operationId": "registryUserDeleteSingle", "parameters": [ { "name": "shortname", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the organization" }, { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The username of the user" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Confirms deletion of the registry user", "content": { "application/json": { "schema": { "$ref": "../schemas/registry-user/delete-registry-user-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/registry/org/{shortname}/user": { "post": { "tags": [ "Data Registry — Users" ], "summary": "Create a user with the provided short name as the owning organization (accessible to Secretariat or target organization Admin)", "description": "Related legacy endpoint: POST /org/{shortname}/user. Uses the Data Registry user request schema, including the required status field. Compare the legacy request schema before switching.
User must belong to an organization with the Secretariat role or be an Admin of the target organization
Admin User: Creates a user for the Admin's organization
Secretariat: Creates a user for any organization
", "operationId": "registryUserCreateSingle", "parameters": [ { "name": "shortname", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the organization" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "The created user, including the generated API key", "content": { "application/json": { "schema": { "$ref": "../schemas/registry-user/create-registry-user-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "../schemas/registry-user/create-registry-user-request.json" }, "example": { "username": "jdoe", "status": "active", "name": { "first": "John", "last": "Doe" } } } } } } }, "/registry/org/{shortname}/user/{username}/reset_secret": { "put": { "tags": [ "Data Registry — Users" ], "summary": "Reset the API key for a user (accessible to self, same-organization Admins, or Secretariat)", "description": "Related legacy endpoint: PUT /org/{shortname}/user/{username}/reset_secret.
Authenticated users can reset their own API secret. Organization admins can reset users in their organization. Secretariat users can reset any user's API secret.
Regular User: Resets user's own API secret
Admin User: Resets any user's API secret in the Admin's organization
Secretariat: Resets any user's API secret
", "operationId": "registryUserResetSecret", "parameters": [ { "name": "shortname", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the organization" }, { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The username of the user" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the new API key", "content": { "application/json": { "schema": { "$ref": "../schemas/user/reset-secret-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/registry/org/{shortname}/oversees/{shortname2}/add": { "post": { "tags": [ "Data Registry — Organizations" ], "summary": "Assigns an organization to report to a ROOT organization (accessible to Secretariat only)", "description": "User must belong to an organization with the Secretariat role.
The organization identified by shortname must have ROOT authority. The organization identified by shortname2 will report to it. If shortname2 already reported to a different ROOT. It will be removed from that and both will receive an audit entry.
", "operationId": "registryOrgAddOverseeRelationship", "parameters": [ { "name": "shortname", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the overseeing ROOT organization" }, { "name": "shortname2", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the reporting organization" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Reports-to relationship added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/registry/org/{shortname}/oversees/{shortname2}/remove": { "post": { "tags": [ "Data Registry — Organizations" ], "summary": "Removes an organization reports-to relationship (accessible to Secretariat only)", "description": "User must belong to an organization with the Secretariat role.
The organization identified by shortname must have ROOT authority. The organization identified by shortname2 will no longer report to it.
", "operationId": "registryOrgRemoveOverseeRelationship", "parameters": [ { "name": "shortname", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the overseeing ROOT organization" }, { "name": "shortname2", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the reporting organization" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Reports-to relationship removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/registry/org/{shortname}/user/{username}/grant-role": { "post": { "tags": [ "Data Registry — Users" ], "summary": "Grants a role to a user (accessible to Secretariat or Org Admin)", "description": "User must belong to an organization with the Secretariat role or be an Admin of the target organization
Admin User: Grants a role to a user in the Admin's organization
Secretariat: Grants a role to a user in any organization
", "operationId": "registryUserGrantRole", "parameters": [ { "name": "shortname", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the organization" }, { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The username of the user" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Role granted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "ADMIN" ] } }, "required": [ "role" ] } } } } } }, "/registry/org/{shortname}/user/{username}/revoke-role": { "post": { "tags": [ "Data Registry — Users" ], "summary": "Revokes a role from a user (accessible to Secretariat or Org Admin)", "description": "User must belong to an organization with the Secretariat role or be an Admin of the target organization
Admin User: Revokes a role from a user in the Admin's organization
Secretariat: Revokes a role from a user in any organization
", "operationId": "registryUserRevokeRole", "parameters": [ { "name": "shortname", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the organization" }, { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The username of the user" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Role revoked successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "ADMIN" ] } }, "required": [ "role" ] } } } } } }, "/registry/org/{shortname}/conversation/{index}": { "put": { "tags": [ "Data Registry — Organizations" ], "summary": "Update the conversation at the given index for the given organization (accessible to Secretariat or original same-organization author)", "description": "User must belong to an organization with the Secretariat role or be the original author of the conversation in the same organization
Original Author: Allowed to update only the message body of a conversation posted by them
Secretariat: Allowed to update the message body and/or visibility of any conversation
", "operationId": "registryOrgUpdateConversation", "parameters": [ { "name": "shortname", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The shortname of the organization" }, { "name": "index", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 0 }, "description": "Zero-based conversation index in chronological order" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the updated conversation", "content": { "application/json": { "schema": { "$ref": "../schemas/conversation/update-conversation-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1 }, "visibility": { "type": "string", "enum": [ "public", "private" ] } }, "anyOf": [ { "required": [ "body" ] }, { "required": [ "visibility" ] } ] }, "example": { "body": "Updated message" } } } } } }, "/registry/users": { "get": { "tags": [ "Data Registry — Users" ], "summary": "Retrieves information about all registered users (accessible to Secretariat)", "description": "Related legacy endpoint: GET /users. Data Registry responses expose status and role; legacy responses expose active and authority.active_roles.
User must belong to an organization with the Secretariat role
Secretariat: Retrieves information about all users for all organizations
", "operationId": "registryUserAll", "parameters": [ { "$ref": "#/components/parameters/pageQuery" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns all users, along with pagination fields if results span multiple pages of data.", "content": { "application/json": { "schema": { "$ref": "../schemas/registry-user/list-registry-users-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/conversation": { "get": { "tags": [ "Conversation" ], "summary": "Retrieves all conversations (accessible to Secretariat only)", "description": "User must belong to an organization with the Secretariat role
Secretariat: Retrieves all conversations
", "operationId": "getAllConversations", "parameters": [ { "name": "page", "in": "query", "description": "The page of the conversation to retrieve", "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns all conversations, along with pagination fields if results span multiple pages of data", "content": { "application/json": { "schema": { "$ref": "../schemas/conversation/list-conversations-response.json" }, "example": { "totalCount": 1, "itemsPerPage": 10, "pageCount": 1, "currentPage": 1, "prevPage": null, "nextPage": null, "conversations": [ { "UUID": "c8a41738-f9d6-4447-9755-9ab0101b7a2d", "target_uuid": "123e4567-e89b-12d3-a456-426614174000", "author_id": "fe566221-6a2c-4279-8800-4d3795325997", "author_name": "John Doe", "body": "This is a conversation message.", "posted_at": "2021-02-12T17:15:37.382Z" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/conversation/target/{uuid}": { "get": { "tags": [ "Conversation" ], "summary": "Retrieves all conversations for a specific target UUID (accessible to Secretariat only)", "description": "User must belong to an organization with the Secretariat role
Secretariat: Retrieves all conversations for the specified target UUID
", "operationId": "getConversationsForTargetUUID", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The UUID of the target entity" }, { "name": "page", "in": "query", "description": "Accepted for compatibility; this endpoint returns all conversations without pagination", "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "All conversations for the target, ordered oldest first", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "../schemas/conversation/conversation.json" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } }, "post": { "tags": [ "Conversation" ], "summary": "Creates a conversation for a specific target UUID (accessible to Secretariat or target organization Admin)", "description": "User must belong to an organization with the Secretariat role or be an Admin of the target organization
Secretariat: Creates a conversation for the specified target UUID
Organization Admin: Creates a conversation only when the target UUID is the admin's organization UUID
", "operationId": "createConversationForTargetUUID", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The UUID of the target entity" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the created conversation", "content": { "application/json": { "schema": { "$ref": "../schemas/conversation/conversation.json" }, "example": { "UUID": "c8a41738-f9d6-4447-9755-9ab0101b7a2d", "target_uuid": "123e4567-e89b-12d3-a456-426614174000", "author_id": "fe566221-6a2c-4279-8800-4d3795325997", "author_name": "John Doe", "body": "This is a conversation message.", "posted_at": "2021-02-12T17:15:37.382Z" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1 }, "visibility": { "type": "string", "enum": [ "public", "private" ] } }, "required": [ "body" ], "description": "Secretariat messages default to private. Organization admin messages are always public." }, "example": { "body": "This is a conversation message.", "visibility": "public" } } } } } }, "/conversation/{uuid}": { "put": { "tags": [ "Conversation" ], "summary": "Updates a conversation by UUID (accessible to Secretariat only)", "description": "User must belong to an organization with the Secretariat role
Secretariat: Updates the conversation with the specified UUID
", "operationId": "updateConversationByUUID", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The UUID of the conversation to update" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the updated conversation", "content": { "application/json": { "schema": { "$ref": "../schemas/conversation/conversation.json" }, "example": { "UUID": "c8a41738-f9d6-4447-9755-9ab0101b7a2d", "target_uuid": "123e4567-e89b-12d3-a456-426614174000", "author_id": "fe566221-6a2c-4279-8800-4d3795325997", "author_name": "John Doe", "body": "This is an updated conversation message.", "visibility": "public", "posted_at": "2021-02-12T17:15:37.382Z", "edited_at": "2021-02-12T17:20:00.000Z" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1 }, "visibility": { "type": "string", "enum": [ "public", "private" ] } }, "anyOf": [ { "required": [ "body" ] }, { "required": [ "visibility" ] } ] }, "example": { "body": "Updated message", "visibility": "public" } } } } } }, "/review/byUUID/{uuid}": { "get": { "tags": [ "Review Object" ], "summary": "Retrieves a review object by its UUID (accessible to Secretariat or same-organization Admin)", "description": "User must belong to an organization with the Secretariat role or have the Admin role for the review object's target organization
", "operationId": "getReviewObjectByUUID", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The UUID of the review object" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the review object", "content": { "application/json": { "schema": { "$ref": "../schemas/review/review.json" }, "example": { "uuid": "c8a41738-f9d6-4447-9755-9ab0101b7a2d", "target_object_uuid": "123e4567-e89b-12d3-a456-426614174000", "status": "pending", "new_review_data": { "long_name": "New Organization Name" }, "created": "2021-02-12T17:15:37.382Z", "last_updated": "2021-02-12T17:15:37.382Z" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/review/org/{identifier}": { "get": { "tags": [ "Review Object" ], "summary": "Retrieves the PENDING review object for an organization (accessible to Secretariat or same-organization Admin)", "description": "User must belong to an organization with the Secretariat role or have the Admin role for the requested organization
", "operationId": "getReviewObjectByOrgIdentifier", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The short name or UUID of the organization" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "The pending review, or { pendingReview: null } if none exists", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "../schemas/review/review.json" }, { "type": "object", "properties": { "pendingReview": { "type": "object", "nullable": true, "enum": [ null ] } }, "required": [ "pendingReview" ] } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/review/orgs": { "get": { "tags": [ "Review Object" ], "summary": "Retrieves all review objects (accessible to Secretariat only)", "description": "User must belong to an organization with the Secretariat role
", "operationId": "getAllReviewObjects", "parameters": [ { "name": "page", "in": "query", "description": "The page of results to retrieve", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Filter by review object status", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns a list of review objects", "content": { "application/json": { "schema": { "$ref": "../schemas/review/list-reviews-response.json" }, "example": { "totalCount": 1, "itemsPerPage": 100, "pageCount": 1, "currentPage": 1, "prevPage": null, "nextPage": null, "reviewObjects": [ { "uuid": "c8a41738-f9d6-4447-9755-9ab0101b7a2d", "target_object_uuid": "123e4567-e89b-12d3-a456-426614174000", "status": "pending", "new_review_data": { "long_name": "New Organization Name" }, "created": "2021-02-12T17:15:37.382Z", "last_updated": "2021-02-12T17:15:37.382Z" } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/review/org/{identifier}/reviews": { "get": { "tags": [ "Review Object" ], "summary": "Retrieves the review history for an organization (accessible to Secretariat or same-organization Admin)", "description": "User must belong to an organization with the Secretariat role or have the Admin role for the requested organization
", "operationId": "getReviewHistoryByOrgShortNamePaginated", "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The short name of the organization" }, { "name": "page", "in": "query", "description": "The page of results to retrieve", "schema": { "type": "integer" } }, { "name": "include_conversations", "in": "query", "description": "Whether to include conversation history", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the review history", "content": { "application/json": { "schema": { "$ref": "../schemas/review/list-reviews-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/review/{uuid}": { "put": { "tags": [ "Review Object" ], "summary": "Updates a review object (accessible to Secretariat only)", "description": "User must belong to an organization with the Secretariat role
", "operationId": "updateReviewObjectByReviewUUID", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The UUID of the review object" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the updated review object", "content": { "application/json": { "schema": { "$ref": "../schemas/review/review.json" }, "example": { "uuid": "c8a41738-f9d6-4447-9755-9ab0101b7a2d", "target_object_uuid": "123e4567-e89b-12d3-a456-426614174000", "status": "pending", "new_review_data": { "long_name": "New Organization Name" }, "created": "2021-02-12T17:15:37.382Z", "last_updated": "2021-02-12T17:15:37.382Z" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "../schemas/registry-org/update-registry-org-request.json" }, "example": { "short_name": "example_cna", "long_name": "New Organization Name", "authority": [ "CNA" ], "id_quota": 1000 } } } } } }, "/review/{uuid}/reject": { "put": { "tags": [ "Review Object" ], "summary": "Rejects a review object (accessible to Secretariat only)", "description": "User must belong to an organization with the Secretariat role
", "operationId": "rejectReviewObject", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The UUID of the review object" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the rejected review object", "content": { "application/json": { "schema": { "$ref": "../schemas/review/review.json" }, "example": { "uuid": "c8a41738-f9d6-4447-9755-9ab0101b7a2d", "target_object_uuid": "123e4567-e89b-12d3-a456-426614174000", "status": "rejected", "new_review_data": { "long_name": "New Organization Name" }, "created": "2021-02-12T17:15:37.382Z", "last_updated": "2021-02-12T17:15:37.382Z" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/notification": { "get": { "tags": [ "Notification" ], "summary": "Retrieves notifications for the authenticated user", "description": "", "operationId": "getNotifications", "parameters": [ { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Notifications ordered newest first", "content": { "application/json": { "schema": { "$ref": "../schemas/notification/list-notifications-response.json" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/notification/{uuid}": { "delete": { "tags": [ "Notification" ], "summary": "Dismisses one notification for the authenticated user", "description": "", "operationId": "dismissNotification", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "204": { "description": "Notification dismissed" }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Notification was not found for the authenticated user" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/notification/target/{user_uuid}": { "post": { "tags": [ "Notification" ], "summary": "Creates a notification for an existing user (Secretariat only)", "description": "", "operationId": "createNotificationForUser", "parameters": [ { "name": "user_uuid", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "201": { "description": "Notification created", "content": { "application/json": { "schema": { "$ref": "../schemas/notification/notification.json" } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Secretariat access required", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body", "type" ], "properties": { "body": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "PRIVATE_MESSAGE", "PUBLIC_MESSAGE" ] }, "links": { "type": "object", "properties": { "org_shortname": { "type": "string" }, "user_shortname": { "type": "string" } } } } }, "example": { "body": "A new message is available.", "type": "PUBLIC_MESSAGE" } } } } } }, "/audit/org/": { "post": { "tags": [ "Audit" ], "summary": "Creates a new audit document (accessible to Secretariat only)", "description": "User must belong to an organization with the Secretariat role
", "operationId": "auditCreateSingle", "parameters": [ { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "The audit document and confirmation message", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "created": { "$ref": "../schemas/Audit.json" } }, "required": [ "message", "created" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "../schemas/Audit.json" }, "example": { "target_uuid": "123e4567-e89b-12d3-a456-426614174000", "history": [] } } } } }, "get": { "tags": [ "Audit" ], "summary": "Retrieves all audit documents (accessible to Secretariat only)", "description": "User must belong to an organization with the Secretariat role
", "operationId": "auditGetAll", "parameters": [ { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns all audit documents", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "../schemas/Audit.json" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } }, "put": { "tags": [ "Audit" ], "summary": "Pushes an update to the audit collection history (accessible to Secretariat only)", "description": "User must belong to an organization with the Secretariat role
", "operationId": "auditUpdate", "parameters": [ { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "The audit document and confirmation message", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "updated": { "$ref": "../schemas/Audit.json" } }, "required": [ "message", "updated" ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "The history entry to append" }, "example": { "target_uuid": "123e4567-e89b-12d3-a456-426614174000", "history": [ { "timestamp": "2021-02-12T17:15:37.382Z", "audit_object": { "name": "Updated Org" }, "change_author": "fe566221-6a2c-4279-8800-4d3795325997" } ] } } } } } }, "/audit/org/document/{document_uuid}": { "get": { "tags": [ "Audit" ], "summary": "Retrieves an audit document by its UUID (accessible to Secretariat only)", "description": "User must belong to an organization with the Secretariat role
", "operationId": "auditGetByUUID", "parameters": [ { "name": "document_uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The UUID of the audit document" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the specified audit document", "content": { "application/json": { "schema": { "$ref": "../schemas/Audit.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/audit/org/{org_identifier}": { "get": { "tags": [ "Audit" ], "summary": "Retrieves an audit document by organization identifier (accessible to Secretariat only)", "description": "User must belong to an organization with the Secretariat role
", "operationId": "auditGetByOrgIdentifier", "parameters": [ { "name": "org_identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The short name or UUID of the organization" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "The audit document, or an empty array when the organization does not exist", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "../schemas/Audit.json" }, { "type": "array", "items": {}, "maxItems": 0 } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/audit/org/{org_identifier}/{number_of_changes}": { "get": { "tags": [ "Audit" ], "summary": "Retrieves the last X changes for an organization's audit document (accessible to Secretariat only)", "description": "User must belong to an organization with the Secretariat role
", "operationId": "auditGetLastXChanges", "parameters": [ { "name": "org_identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The short name or UUID of the organization" }, { "name": "number_of_changes", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Maximum number of recent changes to retrieve" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "The organization UUID and its latest audit changes", "content": { "application/json": { "schema": { "$ref": "../schemas/audit/last-changes-response.json" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } }, "/glossary": { "get": { "tags": [ "Glossary" ], "summary": "Retrieves all glossary items", "description": "Retrieves all glossary items
", "operationId": "glossaryAll", "parameters": [ { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns a list of all glossary items", "content": { "application/json": { "schema": { "$ref": "../schemas/glossary/list-glossary-items-response.json" }, "example": { "glossary": [ { "services_short_name": "CNA", "label": "CVE Numbering Authority", "def": "An organization responsible for assigning CVE IDs." } ] } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } }, "post": { "tags": [ "Glossary" ], "summary": "Creates a new glossary item (accessible to Secretariat only)", "description": "User must belong to an organization with the Secretariat role
Secretariat: Creates a new glossary item
", "operationId": "glossaryCreate", "parameters": [ { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the created glossary item wrapped in a success message", "content": { "application/json": { "schema": { "$ref": "../schemas/glossary/create-glossary-item-response.json" }, "example": { "message": "CNA glossary item was successfully created.", "created": { "services_short_name": "CNA", "label": "CVE Numbering Authority", "def": "An organization responsible for assigning CVE IDs." } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "../schemas/glossary/glossary.json" }, "example": { "services_short_name": "CNA", "label": "CVE Numbering Authority", "def": "An organization responsible for assigning CVE IDs." } } } } } }, "/glossary/{services_short_name}": { "get": { "tags": [ "Glossary" ], "summary": "Retrieves a single glossary item by its short name", "description": "Retrieves the specified glossary item
", "operationId": "glossarySingle", "parameters": [ { "name": "services_short_name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The short name of the glossary item" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the specified glossary item", "content": { "application/json": { "schema": { "$ref": "../schemas/glossary/glossary.json" }, "example": { "services_short_name": "CNA", "label": "CVE Numbering Authority", "def": "An organization responsible for assigning CVE IDs." } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } }, "put": { "tags": [ "Glossary" ], "summary": "Updates an existing glossary item (accessible to Secretariat only)", "description": "User must belong to an organization with the Secretariat role
Secretariat: Updates the specified glossary item
", "operationId": "glossaryUpdate", "parameters": [ { "name": "services_short_name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The short name of the glossary item" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Returns the updated glossary item wrapped in a success message", "content": { "application/json": { "schema": { "$ref": "../schemas/glossary/update-glossary-item-response.json" }, "example": { "message": "CNA glossary item was successfully updated.", "updated": { "services_short_name": "CNA", "label": "CVE Numbering Authority", "def": "An organization responsible for assigning CVE IDs." } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/bad-request.json" } } } }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "../schemas/glossary/glossary.json" }, "example": { "services_short_name": "CNA", "label": "CVE Numbering Authority", "def": "An organization responsible for assigning CVE IDs." } } } } }, "delete": { "tags": [ "Glossary" ], "summary": "Deletes an existing glossary item (accessible to Secretariat only)", "description": "User must belong to an organization with the Secretariat role
Secretariat: Deletes the specified glossary item
", "operationId": "glossaryDelete", "parameters": [ { "name": "services_short_name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The short name of the glossary item" }, { "$ref": "#/components/parameters/apiEntityHeader" }, { "$ref": "#/components/parameters/apiUserHeader" }, { "$ref": "#/components/parameters/apiSecretHeader" } ], "responses": { "200": { "description": "Confirms deletion of the glossary item" }, "400": { "description": "Bad Request" }, "401": { "description": "Not Authenticated", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "../schemas/errors/generic.json" } } } } } } } }, "components": { "parameters": { "active": { "in": "query", "name": "active", "description": "The new active state for the user entry. Accepted values are 1, true, or yes to indicate true, and 0, false, or no to indicate false", "required": false, "schema": { "type": "boolean" } }, "active_roles_add": { "in": "query", "name": "active_roles.add", "description": "Add an active role to the organization", "required": false, "schema": { "type": "string", "enum": [ "CNA", "SECRETARIAT", "BULK_DOWNLOAD", "ROOT", "ADP" ] } }, "active_roles_remove": { "in": "query", "name": "active_roles.remove", "description": "Remove an active role from the organization", "required": false, "schema": { "type": "string", "enum": [ "CNA", "SECRETARIAT", "BULK_DOWNLOAD", "ROOT", "ADP" ] } }, "activeUserRolesAdd": { "in": "query", "name": "active_roles.add", "description": "Add an active role to the user", "required": false, "schema": { "type": "string", "enum": [ "ADMIN" ] } }, "activeUserRolesRemove": { "in": "query", "name": "active_roles.remove", "description": "Remove an active role from the user", "required": false, "schema": { "type": "string", "enum": [ "ADMIN" ] } }, "apiEntityHeader": { "in": "header", "name": "CVE-API-ORG", "description": "The shortname for the organization associated with the user requesting authentication", "required": true, "schema": { "type": "string" } }, "apiUserHeader": { "in": "header", "name": "CVE-API-USER", "description": "The username for the account making the request", "required": true, "schema": { "type": "string" } }, "apiSecretHeader": { "in": "header", "name": "CVE-API-KEY", "description": "The user's API key", "required": true, "schema": { "type": "string" } }, "amount": { "in": "query", "name": "amount", "description": "Quantity of CVE IDs to reserve", "required": true, "schema": { "type": "integer", "format": "int32" } }, "assigner": { "in": "query", "name": "assigner", "description": "Filter by assigner org UUID", "required": false, "schema": { "type": "string" } }, "assignerShortName": { "in": "query", "name": "assigner_short_name", "description": "Filter by assignerShortName", "required": false, "schema": { "type": "string" } }, "erlCheck": { "in": "query", "name": "erlcheck", "description": "Enables stricter validation that ensures submitted record meets enrichment data requirements. For a record to be enriched, a CVSS score and a CWE ID must be provided.", "required": false, "schema": { "type": "boolean" } }, "batch_type": { "in": "query", "name": "batch_type", "description": "Required when amount is greater than one, determines whether the reserved CVE IDs should be sequential or non-sequential", "required": false, "schema": { "type": "string", "enum": [ "sequential", "non-sequential", "nonsequential" ] } }, "countOnly": { "in": "query", "name": "count_only", "description": "Get count of records that match query. Accepted values are 1, true, or yes to indicate true, and 0, false, or no to indicate false", "required": false, "schema": { "type": "boolean" } }, "nextPage": { "in": "query", "name": "next_page", "description": "Key returned by a GET /cve_cursor call that must be used to get the next page of results in a subsequent call", "required": false, "schema": { "type": "string" } }, "previousPage": { "in": "query", "name": "previous_page", "description": "Key returned by a GET /cve_cursor call that must be used to get the previous page of results in a subsequent call", "required": false, "schema": { "type": "string" } }, "limit": { "in": "query", "name": "limit", "description": "CVE records to return per page. Must be between 1-500. ", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 500 } }, "cnaModified": { "in": "query", "name": "cna_modified", "description": "Only get CVE records with cnaContainers that have been modified/created within the set time_modified range. Requires at least one time_modified parameter set", "required": false, "schema": { "type": "boolean" } }, "adpShortName": { "in": "query", "name": "adp_short_name", "description": "Only get CVE records that have an adpContainer owned by this org.", "required": false, "schema": { "type": "string" } }, "cveState": { "in": "query", "name": "state", "description": "Filter by state", "schema": { "type": "string", "enum": [ "PUBLISHED", "REJECTED" ] } }, "cve_year": { "in": "query", "name": "cve_year", "description": "The year the CVE IDs will be reserved for (i.e., 1999, ..., currentYear + 1)", "required": true, "schema": { "type": "integer", "format": "int32" } }, "cveIdGetFilteredState": { "in": "query", "name": "state", "description": "Filter by state ", "required": false, "schema": { "type": "string", "enum": [ "RESERVED", "PUBLISHED", "REJECTED" ] } }, "cveIdGetFilteredCveIdYear": { "in": "query", "name": "cve_id_year", "description": "Filter by the year of the CVE IDs", "required": false, "schema": { "type": "string" } }, "cveIdGetFilteredTimeReservedLt": { "in": "query", "name": "time_reserved.lt", "description": "Most recent reserved timestamp to retrieve. Include with all requests potentially returning multiple pages of CVE IDs to avoid issues if new IDs are reserved during use.