From 6fbed8171f84b10b7b1515853975f1b2ef56965e Mon Sep 17 00:00:00 2001 From: Lakshman Patel Date: Sun, 26 Jul 2026 14:15:34 +0530 Subject: [PATCH] fix: update api/openapi.yaml to match hawk repo contract --- api/openapi.yaml | 189 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 128 insertions(+), 61 deletions(-) diff --git a/api/openapi.yaml b/api/openapi.yaml index a767d7a..e8bf615 100644 --- a/api/openapi.yaml +++ b/api/openapi.yaml @@ -125,23 +125,15 @@ components: tool_calls: type: integer - Message: + GraphScope: type: object properties: - role: + tenant_id: type: string - enum: [user, assistant, tool] - content: + project_id: + type: string + repository_id: type: string - tool_use: {} - tool_results: {} - - GraphScope: - type: object - properties: - tenant_id: {type: string} - project_id: {type: string} - repository_id: {type: string} GraphRef: type: object @@ -150,91 +142,147 @@ components: kind: type: string enum: [system, knowledge, execution, policy, quality, operations] - id: {type: string} + id: + type: string + + GraphArtifactRef: + type: object + required: [uri] + properties: + uri: + type: string + digest: + type: string + media_type: + type: string GraphProvenance: type: object required: [producer] properties: - producer: {type: string} - version: {type: string} - source_id: {type: string} + producer: + type: string + version: + type: string + source_id: + type: string evidence: type: array items: - type: object - required: [uri] - properties: - uri: {type: string} - digest: {type: string} - media_type: {type: string} + $ref: "#/components/schemas/GraphArtifactRef" GraphNode: type: object required: [id, kind, created_at, provenance] properties: - id: {type: string} + id: + type: string kind: type: string enum: [system, knowledge, execution, policy, quality, operations] - scope: {$ref: "#/components/schemas/GraphScope"} - created_at: {type: string, format: date-time} - effective_at: {type: string, format: date-time} - provenance: {$ref: "#/components/schemas/GraphProvenance"} + scope: + $ref: "#/components/schemas/GraphScope" + created_at: + type: string + format: date-time + effective_at: + type: string + format: date-time + provenance: + $ref: "#/components/schemas/GraphProvenance" attributes: type: object - additionalProperties: {type: string} + additionalProperties: + type: string GraphEdge: type: object required: [id, kind, from, to, created_at, provenance] properties: - id: {type: string} + id: + type: string kind: type: string enum: [contains, depends_on, references, produced, governed_by, validated_by] - from: {$ref: "#/components/schemas/GraphRef"} - to: {$ref: "#/components/schemas/GraphRef"} - scope: {$ref: "#/components/schemas/GraphScope"} - created_at: {type: string, format: date-time} - effective_at: {type: string, format: date-time} - provenance: {$ref: "#/components/schemas/GraphProvenance"} + from: + $ref: "#/components/schemas/GraphRef" + to: + $ref: "#/components/schemas/GraphRef" + scope: + $ref: "#/components/schemas/GraphScope" + created_at: + type: string + format: date-time + effective_at: + type: string + format: date-time + provenance: + $ref: "#/components/schemas/GraphProvenance" attributes: type: object - additionalProperties: {type: string} + additionalProperties: + type: string GraphEvent: type: object required: [id, type, subject, occurred_at, provenance] properties: - id: {type: string} + id: + type: string type: type: string enum: [created, updated, transitioned, observed, deleted] - subject: {$ref: "#/components/schemas/GraphRef"} - scope: {$ref: "#/components/schemas/GraphScope"} - occurred_at: {type: string, format: date-time} - correlation_id: {type: string} - causation_id: {type: string} - idempotency_key: {type: string} - provenance: {$ref: "#/components/schemas/GraphProvenance"} + subject: + $ref: "#/components/schemas/GraphRef" + scope: + $ref: "#/components/schemas/GraphScope" + occurred_at: + type: string + format: date-time + correlation_id: + type: string + causation_id: + type: string + idempotency_key: + type: string + provenance: + $ref: "#/components/schemas/GraphProvenance" ExecutionGraph: type: object required: [schema_version, generated_at, scope, nodes, edges, events] properties: - schema_version: {type: string, enum: [hawk.graph/v1]} - generated_at: {type: string, format: date-time} - scope: {$ref: "#/components/schemas/GraphScope"} + schema_version: + type: string + enum: [hawk.graph/v1] + generated_at: + type: string + format: date-time + scope: + $ref: "#/components/schemas/GraphScope" nodes: type: array - items: {$ref: "#/components/schemas/GraphNode"} + items: + $ref: "#/components/schemas/GraphNode" edges: type: array - items: {$ref: "#/components/schemas/GraphEdge"} + items: + $ref: "#/components/schemas/GraphEdge" events: type: array - items: {$ref: "#/components/schemas/GraphEvent"} + items: + $ref: "#/components/schemas/GraphEvent" + + Message: + type: object + properties: + role: + type: string + enum: [user, assistant, tool] + content: + type: string + tool_use: {} + tool_results: {} PaginatedMessages: type: object @@ -564,20 +612,34 @@ paths: get: tags: [graphs] summary: Project a persisted session as a portable execution graph + description: | + Returns Hawk's privacy-safe, read-only `hawk.graph/v1` projection. + Prompt text, tool arguments, tool output, and verification details are + excluded. Explicit Trace checkpoint IDs are additive to authoritative + Trace session correlation performed by Hawk. parameters: - name: id in: path required: true - schema: {type: string, maxLength: 128, pattern: '^[A-Za-z0-9._-]+$'} + schema: + type: string + maxLength: 128 + pattern: '^[A-Za-z0-9._-]+$' - name: repository in: query - schema: {type: string, maxLength: 256} + description: Optional repository scope override. + schema: + type: string + maxLength: 256 - name: trace_checkpoint in: query + description: Optional 12-character lowercase hexadecimal Trace checkpoint ID. May be repeated up to 64 times. schema: type: array maxItems: 64 - items: {type: string, pattern: '^[0-9a-f]{12}$'} + items: + type: string + pattern: '^[0-9a-f]{12}$' style: form explode: true responses: @@ -585,27 +647,32 @@ paths: description: Portable execution graph content: application/json: - schema: {$ref: "#/components/schemas/ExecutionGraph"} + schema: + $ref: "#/components/schemas/ExecutionGraph" "400": - description: Invalid graph request + description: Invalid session, repository, or checkpoint input content: application/json: - schema: {$ref: "#/components/schemas/Error"} + schema: + $ref: "#/components/schemas/Error" "401": description: Unauthorized content: application/json: - schema: {$ref: "#/components/schemas/Error"} + schema: + $ref: "#/components/schemas/Error" "404": description: Session not found content: application/json: - schema: {$ref: "#/components/schemas/Error"} + schema: + $ref: "#/components/schemas/Error" "503": - description: Graph projection unavailable + description: Graph projection is not configured content: application/json: - schema: {$ref: "#/components/schemas/Error"} + schema: + $ref: "#/components/schemas/Error" /v1/stats: get: