REST API OpenAPI spec (#612)

* OpenAPI spec in specs/api.  Checked lint with redoc.

specs/api/components/schemas/query/NlpQueryRequest.yaml

@@ -0,0 +1,17 @@
+type: object
+description: |
+  NLP query request - convert natural language question to structured query.
+required:
+  - question
+properties:
+  question:
+    type: string
+    description: Natural language question
+    example: Who does Alice know that works in engineering?
+  max-results:
+    type: integer
+    description: Maximum results to return when query is executed
+    default: 100
+    minimum: 1
+    maximum: 10000
+    example: 50

specs/api/components/schemas/query/NlpQueryResponse.yaml

@@ -0,0 +1,47 @@
+type: object
+description: NLP query response
+required:
+  - graphql-query
+  - variables
+properties:
+  graphql-query:
+    type: string
+    description: Generated GraphQL query
+    example: |
+      query GetConnections($person: ID!) {
+        person(id: $person) {
+          knows {
+            name
+            worksFor { department }
+          }
+        }
+      }
+  variables:
+    type: object
+    description: Query variables
+    additionalProperties:
+      type: string
+    example:
+      person: "https://example.com/person/alice"
+  detected-schemas:
+    type: array
+    description: Detected schema types used in query
+    items:
+      type: string
+    example: ["Person", "Organization"]
+  confidence:
+    type: number
+    description: Confidence score for query generation (0.0-1.0)
+    minimum: 0.0
+    maximum: 1.0
+    example: 0.87
+  error:
+    type: object
+    description: Error if query generation failed
+    properties:
+      type:
+        type: string
+        example: PARSE_ERROR
+      message:
+        type: string
+        example: Could not understand question structure

specs/api/components/schemas/query/ObjectsQueryRequest.yaml

@@ -0,0 +1,40 @@
+type: object
+description: |
+  Objects query request - GraphQL query over knowledge graph.
+required:
+  - query
+properties:
+  query:
+    type: string
+    description: GraphQL query string
+    example: |
+      query GetPerson($id: ID!) {
+        person(id: $id) {
+          name
+          email
+          knows {
+            name
+          }
+        }
+      }
+  variables:
+    type: object
+    description: GraphQL query variables
+    additionalProperties:
+      type: string
+    example:
+      id: "https://example.com/person/alice"
+  operation-name:
+    type: string
+    description: Operation name (for multi-operation documents)
+    example: GetPerson
+  user:
+    type: string
+    description: User identifier
+    default: trustgraph
+    example: alice
+  collection:
+    type: string
+    description: Collection to query
+    default: default
+    example: research

specs/api/components/schemas/query/ObjectsQueryResponse.yaml

@@ -0,0 +1,54 @@
+type: object
+description: Objects query response (GraphQL format)
+properties:
+  data:
+    description: GraphQL response data (JSON object or null)
+    oneOf:
+      - type: object
+        additionalProperties: {}
+      - type: "null"
+    example:
+      person:
+        name: Alice
+        email: alice@example.com
+        knows:
+          - name: Bob
+          - name: Carol
+  errors:
+    type: array
+    description: GraphQL field-level errors
+    items:
+      type: object
+      properties:
+        message:
+          type: string
+          description: Error message
+          example: Cannot query field 'age' on type 'Person'
+        path:
+          type: array
+          description: Path to error location
+          items:
+            type: string
+          example: ["person", "age"]
+        extensions:
+          type: object
+          description: Additional error metadata
+          additionalProperties:
+            type: string
+  extensions:
+    type: object
+    description: Query metadata (execution time, etc.)
+    additionalProperties:
+      type: string
+    example:
+      execution_time_ms: "42"
+  error:
+    type: object
+    description: System-level error (connection, timeout, etc.)
+    properties:
+      type:
+        type: string
+        example: TIMEOUT_ERROR
+      message:
+        type: string
+        example: Query execution timeout

specs/api/components/schemas/query/StructuredQueryRequest.yaml

@@ -0,0 +1,22 @@
+type: object
+description: |
+  Structured query request - natural language question with automatic execution.
+
+  Combines NLP query generation and execution in one call.
+required:
+  - question
+properties:
+  question:
+    type: string
+    description: Natural language question
+    example: Who does Alice know that works in engineering?
+  user:
+    type: string
+    description: User identifier
+    default: trustgraph
+    example: alice
+  collection:
+    type: string
+    description: Collection to query
+    default: default
+    example: research

specs/api/components/schemas/query/StructuredQueryResponse.yaml

@@ -0,0 +1,34 @@
+type: object
+description: Structured query response
+properties:
+  data:
+    description: Query results (JSON object or null)
+    oneOf:
+      - type: object
+        additionalProperties: {}
+      - type: "null"
+    example:
+      person:
+        name: Alice
+        knows:
+          - name: Bob
+            worksFor: {name: Acme Corp, department: Engineering}
+          - name: Carol
+            worksFor: {name: Tech Inc, department: Engineering}
+  errors:
+    type: array
+    description: Query errors (array of error strings)
+    items:
+      type: string
+    example:
+      - Could not resolve field 'age' on type 'Person'
+  error:
+    type: object
+    description: System-level error
+    properties:
+      type:
+        type: string
+        example: QUERY_GENERATION_ERROR
+      message:
+        type: string
+        example: Failed to generate query from question

specs/api/components/schemas/query/TriplesQueryRequest.yaml

@@ -0,0 +1,30 @@
+type: object
+description: |
+  Triples query request - query knowledge graph by subject/predicate/object pattern.
+properties:
+  s:
+    $ref: '../../common/RdfValue.yaml'
+    description: Subject filter (optional)
+  p:
+    $ref: '../../common/RdfValue.yaml'
+    description: Predicate filter (optional)
+  o:
+    $ref: '../../common/RdfValue.yaml'
+    description: Object filter (optional)
+  limit:
+    type: integer
+    description: Maximum number of triples to return
+    default: 10000
+    minimum: 1
+    maximum: 100000
+    example: 100
+  user:
+    type: string
+    description: User identifier
+    default: trustgraph
+    example: alice
+  collection:
+    type: string
+    description: Collection to query
+    default: default
+    example: research

specs/api/components/schemas/query/TriplesQueryResponse.yaml

@@ -0,0 +1,10 @@
+type: object
+description: Triples query response
+required:
+  - response
+properties:
+  response:
+    type: array
+    description: Matching triples
+    items:
+      $ref: '../../common/Triple.yaml'