diff --git a/openapi.yaml b/openapi.yaml
new file mode 100644
index 000000000..20e68a5cd
--- /dev/null
+++ b/openapi.yaml
@@ -0,0 +1,220 @@
+# this API specification is draft and subject to change.
+openapi: "3.0.2"
+info:
+  title: CVE Services API
+  description: The CVE services API which supports automation tooling for the CVE Project.
+  version: 0.1.0
+  contact:
+    "name": "API Support"
+    "url": http://cve.org/api
+    "email": api@mitre.org
+  license:
+    name: Creative Commons Zero v1.0 Universal
+    url: https://creativecommons.org/publicdomain/zero/1.0/legalcode
+  termsOfService: http://cve.org/api/terms
+# The following is notional
+servers:
+  - url: https://api-dev.cve.org/v1
+    description: Development and testing server
+  - url: https://api.cve.org/v1
+    description: Production server
+components:
+  parameters:
+    cve-id-path:
+      name: cve-id
+      in: path
+      description: The CVE id for which the record is being submitted
+      required: true
+      schema:
+        # CVE ID format
+        type: string
+        pattern: 'CVE-\d{4}-\d+'
+    api-entity-header:
+      name: X-API-ENTITY
+      description: >
+        The entity (e.g., CNA, ADP) that is authenticated or requesting authentication. \[TODO:: Is there a pattern for the format?\]
+      in: header
+      required: true
+      schema:
+        type: string
+    api-secret-header:
+      name: X-API-SECRET
+      description: >
+        The entity's (e.g., CNA, ADP) secret. \[TODO:: Is there a pattern for the format?\]
+      in: header
+      required: true
+      schema:
+        type: string
+paths:
+  # CVE submission and retrieval service
+  /cve/{cve-id}:
+    parameters:
+      - "$ref": "#/components/parameters/cve-id-path"
+    get:
+      summary: Retrieves a CVE record by id
+      operationId: getCVERecordById
+      responses:
+        200:
+          description: >
+            The requested CVE record associated with the CVE ID is returned.
+          content:
+            application/json:
+              schema:
+                type: object
+                # add schema for CVE 5.0 format
+        404:
+          description: The requested CVE ID has not been populated.
+    post:
+      summary: Creates a new CVE record entry
+      operationId: submitCVERecordById
+      parameters:
+        - "$ref": "#/components/parameters/api-entity-header"
+        - "$ref": "#/components/parameters/api-secret-header"
+        - name: X-API-AUTHOR
+          in: header
+          required: true
+          schema:
+            type: string
+      requestBody:
+        description: The CVE record data to populate
+        content:
+          application/json:
+            schema:
+              type: object
+              # add schema for CVE 5.0 format
+      responses:
+        200:
+          description: the CVE record is posted
+          content:
+            application/json:
+              schema:
+                type: object
+                # schema for the body
+        400:
+          description: the request body is malformed
+        401:
+          description: the client is not authenticated
+        403:
+          description: >
+            the client is not authorized to submit this CVE. A likely
+            cause is the client's authentication context is not
+            associated with the reserved CVE id.
+        404:
+          description: >
+            the requested CVE ID has not been reserved \[TODO:: do we want
+            this as it leaks info about the reserved status of a CVE ID? \]
+    put:
+      summary: Updates an existing CVE record entry
+      operationId: updateCVERecordById
+      parameters:
+        - "$ref": "#/components/parameters/api-entity-header"
+        - "$ref": "#/components/parameters/api-secret-header"
+        - name: X-API-AUTHOR
+          in: header
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: the update has been applied
+          content:
+            application/json:
+              schema:
+                # schema for the body
+        400:
+          description: the request body is malformed
+        401:
+          description: the client is not authenticated
+        403:
+          description: >
+            the client is not authorized to update this CVE or a part that was
+            changed. The latter might be caused by a change to a record
+            container for which the authenticated entity is not authorized to
+            change.
+        404:
+          description: >
+            the requested CVE ID has not been previously published.
+      requestBody:
+        description: The CVE record data to update
+        content:
+          application/json:
+            schema:
+              type: object
+              # add schema for CVE 5.0 format
+  /cve/{cve-id}/{entity-type}/{entity-id}:
+    parameters:
+      - "$ref": "#/components/parameters/cve-id-path"
+      - name: entity-type
+        in: path
+        description: The type of entity (i.e., CNA, ADP)
+        required: true
+        schema:
+          type: string
+          enum:
+            - CNA
+            - ADP
+      - name: entity-id
+        in: path
+        description: The identifier for the entity's container
+        required: true
+        schema:
+          type: string
+          # what is this syntax?
+    get:
+      description: >
+        Retrieves a given container in a CVE record entry.
+      operationId: getCVERecordContainerById
+      responses:
+        200:
+          description: >
+            The requested CVE record container associated with the CVE ID and entity is returned.
+          content:
+            application/json:
+              schema:
+                type: object
+                # add schema for CVE 5.0 format
+        404:
+          description: The requested CVE ID or container has not been populated.
+    put:
+      description: >
+        Updates a given container in a CVE record entry.
+      operationId: updateCVERecordContainerById
+      parameters:
+        - "$ref": "#/components/parameters/api-entity-header"
+        - "$ref": "#/components/parameters/api-secret-header"
+        - name: X-API-AUTHOR
+          in: header
+          required: true
+          schema:
+            type: string
+      requestBody:
+        description: The CVE record container data to update
+        content:
+          application/json:
+            schema:
+              # add schema for CVE 5.0 format
+      responses:
+        200:
+          description: the update has been applied
+          content:
+            application/json:
+              schema:
+                # schema for the body
+        400:
+          description: the request body is malformed
+        401:
+          description: the client is not authenticated
+        403:
+          description: >
+            the client is not authorized to update this CVE or a part that was
+            changed. The latter might be caused by a change to a record
+            container for which the authenticated entity is not authorized to
+            change.
+        404:
+          description: >
+            the requested CVE ID has not been previously published.
+#  /cve-id:
+#    post:
+#  /cve-id/{cve-id}:
+#    get:
+#    delete: