Skip to content

Merge feature branch into main #29

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Patel230 merged 2 commits into from
Jul 26, 2026
Merged

Merge feature branch into main #29

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
502cbe2
Merge main
Patel230 Jul 26, 2026
6fbed81
fix: update api/openapi.yaml to match hawk repo contract
Patel230 Jul 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
189 changes: 128 additions & 61 deletions api/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -564,48 +612,67 @@ 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:
"200":
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:
Expand Down
Loading