--- title: "Primary Endpoints" slug: "primary-endpoints" updated: 2024-09-11T20:38:39Z published: 2024-09-11T20:38:39Z canonical: "docs.oscal.io/primary-endpoints" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.oscal.io/llms.txt > Use this file to discover all available pages before exploring further. # Primary Endpoints **Primary Endpoints** interact with the working copy of the OSCAL files themselves. The following methods apply to every defined OSCAL model. | **Method** | **Description** | | --- | --- | | `GET /{model-name}` | Lists all items of that model type for which the user has access, including each item's ID and Title. | | `POST /{model-name}` | Adds a new item of that model type. | | `GET /{model-name}/{content-uuid}` | Gets a specific item of that model type by its identifier. | | `PUT /{model-name}/{content-uuid}` | Replaces a specific item of that model type by its identifier. | | `DELETE /{model-name}/{content-uuid}` | Removes a specific item of that model type by its identifier. | ### GET /{model-name} `GET /{model-name}` returns a list of accessible content for the specified `{model name}`. This list is always returned as JSON. Each item in the list includes its `content-uuid`, which the client can later use for endpoints that require it. The implementation *should* filter this list to only those items [accessible by the asserted identity](https://docs.oscal.io/docs/supporting-information#access-control). #### Example `GET /catalog` **Returns:** ``` { "catalog-list": [ { "content-uuid": "2b51910e-3ffd-432d-92fb-c3ff82a97bd2", "title": "First Catalog", "published": "2024-09-10T14:00:00Z", "version": "1.0", "oscal-version": "1.1.2", "document-ids": [ { "scheme": "http://oscal.io/oscal/identifier/content-uuid", "identifier": "2b51910e-3ffd-432d-92fb-c3ff82a97bd2" } ], "markings": [ "FOR OFFICIAL USE ONLY " ], "remarks": "Optional remarks about this catalog" }, { "content-uuid": "cfc31580-33ef-408c-8def-2bfc316222e3", "title": "Second Catalog", "published": "2024-09-10T14:00:00Z", "version": "4.4", "oscal-version": "1.1.2", "document-ids": [ { "scheme": "http://oscal.io/oscal/identifier/content-uuid", "identifier": "cfc31580-33ef-408c-8def-2bfc316222e3" } ], "markings": [] } ] } ``` ### POST /{model-name} `POST /{model-name}` directs the implementation to receive valid OSCAL content and store it. Upon receipt the implementation *must*: 1. check the `Content-type` header to ensure it specifies the OSCAL format being transmitted. The implementation *must* only accept `application/json`, `application/xml` or `application/yaml`. 2. ensure the content matches the declared format above and is OSCAL-valid for that format; 3. check for an existing content identifier in the `document-ids` array (`//metaschema/document-ids`), as indicated by the `scheme` value `http://oscal.io/oscal/identifier/content-uuid`; and 4. store the content. **NOTES:** - If the `Content-type` header is not present or contains an unrecognized value, the implementation *should* return an error, but *may* assume the format is JSON and attempt to continue. - If the content is not OSCAL-valid to its declared OSCAL version (`//metadata/oscal-version`), the implementation *must* return an error, and *should* include specific validation errors. - If a content identifier already exists and is a valid v4 or v5 UUID, the implementation *must* use this as the `content-uuid`. - If a content identifier already exists, but is not a valid v4 or v5 UUID, the implementation *should* either: - reject the content as invalid; or - correct the error by generating an [RFC-4122 compliant](https://datatracker.ietf.org/doc/html/rfc4122) v4 or v5 UUID and replacing the invalid identifier. - If no content identifier is defined in the `document-ids`, the implementation *must* generate an [RFC-4122 compliant](https://datatracker.ietf.org/doc/html/rfc4122) v4 or v5 UUID and insert it into the `document-ids` array. - NOTE: RFC-4122 requires only lower-case characters for hex values `a` through `f` in UUID values. - The implementation *should* enforce [access control](https://docs.oscal.io/docs/supporting-information#access-control) and only allow content to be submitted when the asserted identity has explicit permission to do so. ### GET /{model-name}/{content-uuid} `GET /{model-name}/{content-uuid}` directs the implementation to deliver the OSCAL referenced by the `content-uuid`. content receive valid OSCAL content and store it. Upon receipt of this request, the implementation *must*: 1. check the `Accept` header to determine the OSCAL format requested by the client; 2. respond to the request with: a. the OSCAL content as the payload; and b. the `Content-type` header to set to either `application/json`, `application/xml` or `application/yaml`. **NOTES:** - The implementation *must* honor the `Accept` header as follows. When `Accept` is set to: - `application/json` or `application/oscal+json` return the OSCAL content in JSON format; - `application/xml` (preferred by RFC 7303) or `text/xml` (deprecated by RFC 7303) or `application/oscal+xml` return the OSCAL content in XML format; or - `application/yaml` or `text/yaml` return the OSCAL content in YAML format. - The implementation *must* set the payload to only include serialized XML, JSON or YAML content that is OSCAL-valid to the client upon receipt with no manipulation. - The implementation *should* enforce [access control](https://docs.oscal.io/docs/supporting-information#access-control) and only return content when the asserted identity has explicit permission to access the content requested. ### PUT /{model-name}/{content-uuid} `PUT /{model-name}/{content-uuid}` directs the implementation to receive valid OSCAL content and use it to replace existing OSCAL content. Upon receipt the implementation *must*: 1. check the `Content-type` header to ensure it specifies the OSCAL format being transmitted. The implementation *must* only accept `application/json`, `application/xml` or `application/yaml`. 2. ensure the content matches the declared format above and is OSCAL-valid for that format; 3. check for an existing content identifier in the `document-ids` array (`//metaschema/document-ids`), as indicated by the `scheme` value `http://oscal.io/oscal/identifier/content-uuid`; and 4. replace the prior content with the newly provided content. **NOTES:** - If the `Content-type` header is not present or contains an unrecognized value, the implementation *should* return an error, but *may* assume the format is JSON and attempt to continue. - If the content is not OSCAL-valid to its declared OSCAL version (`//metadata/oscal-version`), the implementation *must* return an error, and *should* include specific validation errors. - If a content identifier already exists, is a valid v4 or v5 UUID, but does not match the `content-uuid` used in the endpoint, the implementation *should* either: - reject the content and raise an error; or - allow more than one and honor both. - If a content identifier already exists, but is not a valid v4 or v5 UUID, the implementation *should* either: - reject the content as invalid; or - correct the error by generating an [RFC-4122 compliant](https://datatracker.ietf.org/doc/html/rfc4122) v4 or v5 UUID and replacing the invalid identifier. - NOTE: RFC-4122 requires only lower-case characters for hex values `a` through `f` in UUID values. - The implementation *should* enforce [access control](https://docs.oscal.io/docs/supporting-information#access-control) and only allow the replacement of content when the asserted identity has explicit permission to do so. ### DELETE /{model-name}/{content-uuid} `DELETE /{model-name}/{content-uuid}` directs the implementation to remove the referenced OSCAL content from the local datastore. Upon receipt of this request, the implementation *must*: - identify and delete the content itself; - delete any associated snapshots; and - delete any associated attachments. **NOTES:** - The implementation *may* perform the three delete activities (content, snapshot and attachments) in any order it sees fit. - If the deleted content is subject to record retention policies, litigation holds, or other requirements, the implementation *may* either: - block the delete and return an error; or - render the content unavailable via the API, but otherwise retain it as required. - If the deleted content still exists within system backups, the implementation's owning organization *may* handle those backups in accordance with organizational requirements. - If deleted records are retained for any reason, the organization *should* take reasonable steps to notify the user of retention. - The implementation *should* enforce [access control](https://docs.oscal.io/docs/supporting-information#access-control) and only delete content when the asserted identity has explicit permission to do so.