API Reference

🦭 Grey Seal · Go Ollama PostgreSQL RAG

Protocol Documentation

schemas/greyseal/v1/agent.proto
- AgentRun
schemas/greyseal/v1/conversation.proto
schemas/greyseal/v1/resource.proto
- Resource
- Source
schemas/greyseal/v1/role.proto
- Role
schemas/greyseal/v1/services/agent.proto
schemas/greyseal/v1/services/conversation.proto
schemas/greyseal/v1/services/resource.proto
schemas/greyseal/v1/services/role.proto
Scalar Value Types

schemas/greyseal/v1/agent.proto

AgentRun

AgentRun is the persisted state of one agentic coding-task run.

Field	Type	Description
uuid	string
provider	string	provider: "claude" (Managed Agents) — the only implemented value in Phase 1. "ollama:<model>" is a reserved, not-yet-implemented value.
repo_url	string
status	string	status: "running"
session_id	string	session_id is the provider's session identifier — for Claude this is a Managed Agents session ID, usable to build a Console trace-view link.
pr_url	string	pr_url is populated once the agent opens a pull request, if it does.
error	string	error holds a human-readable failure reason when status is "error".
created_at	google.protobuf.Timestamp
updated_at	google.protobuf.Timestamp

Top

schemas/greyseal/v1/conversation.proto

Conversation

Conversation is a chat session that persists and can be resumed.

Field	Type	Label	Description
uuid	string
title	string		title is an optional display name; can be set manually or auto-generated from the first exchange.
role_uuid	string		role_uuid optionally links to a Role that sets the system prompt.
resource_uuids	string	repeated	resource_uuids optionally scopes retrieval to a specific set of resources. When empty, all indexed resources are searched.
summary	string		summary holds a rolling compressed summary of older messages to manage context window length.
messages	Message	repeated
created_at	google.protobuf.Timestamp
updated_at	google.protobuf.Timestamp

Message

Message is a single turn in a conversation.

Field	Type	Label	Description
uuid	string
conversation_uuid	string
role	MessageRole
content	string
resource_uuids	string	repeated	resource_uuids holds references to indexed resources used to generate this response (populated for ASSISTANT messages).
feedback	int32		feedback allows simple quality tracking: -1 negative, 0 neutral, 1 positive.
created_at	google.protobuf.Timestamp

MessageRole

Name	Number	Description
MESSAGE_ROLE_UNSPECIFIED	0
MESSAGE_ROLE_USER	1
MESSAGE_ROLE_ASSISTANT	2

Top

schemas/greyseal/v1/resource.proto

Resource

Resource represents an ingested and indexed document used as conversation context.

Field	Type	Label	Description
uuid	string
name	string
service	string
entity	string
source	Source
path	string
created_at	google.protobuf.Timestamp
indexed_at	google.protobuf.Timestamp

Source

Name	Number	Description
SOURCE_UNSPECIFIED	0
SOURCE_WEBSITE	1
SOURCE_PDF	2
SOURCE_TEXT	3

Top

schemas/greyseal/v1/role.proto

Role

Role is a reusable named system prompt that can be assigned to a conversation to shape how the chatbot responds. Leaving role_uuid blank on a conversation means no system prompt is applied.

Field	Type	Label	Description
uuid	string
name	string
system_prompt	string
created_at	google.protobuf.Timestamp

Top

schemas/greyseal/v1/services/agent.proto

AgentRunEvent

AgentRunEvent is one relayed event from a running agent session.

Field	Type	Description
type	string	type: the provider event type, e.g. "agent.message", "agent.tool_use", "session.status_idle", "session.status_terminated".
message	string	message is human-readable text for message/tool-use events.
status	string	status is populated on status-change events: "running"

GetAgentRunRequest

Field	Type	Label	Description
uuid	string

GetAgentRunResponse

Field	Type	Label	Description
data	schemas.greyseal.v1.AgentRun

RunAgentTaskRequest

Field	Type	Description
provider	string	provider: "claude" (only implemented value); "ollama:<model>" reserved.
repo_url	string
github_token	string	github_token authorizes cloning (and, for Claude, opening a PR against) repo_url. Never persisted — used only to start the provider session.
branch	string	branch to check out; defaults to the repository's default branch.
task_description	string	task_description is what the agent should do.
rubric	string	rubric is the grading criteria for the provider's outcome-graded loop, e.g. "go build ./… succeeds, go test ./… passes, no TODO(agent) markers remain".

RunAgentTaskResponse

Field	Type	Label	Description
data	schemas.greyseal.v1.AgentRun

StreamAgentRunRequest

Field	Type	Label	Description
uuid	string

AgentService

Method Name	Request Type	Response Type	Description
RunAgentTask	RunAgentTaskRequest	RunAgentTaskResponse	RunAgentTask starts a new agentic coding-task run and returns immediately with its initial state; the run continues asynchronously on the provider's side.
GetAgentRun	GetAgentRunRequest	GetAgentRunResponse	GetAgentRun returns the current state of a previously started run.
StreamAgentRun	StreamAgentRunRequest	AgentRunEvent stream	StreamAgentRun streams events for a run as they occur, until the run reaches a terminal status.

Top

schemas/greyseal/v1/services/conversation.proto

ChatRequest

Field	Type	Label	Description
conversation_uuid	string
content	string

ChatResponse

ChatResponse is streamed; each message carries one token or chunk of content. The final message in the stream includes the fully-populated Message with resource references and uuid set.

Field	Type	Label	Description
token	string
final_message	schemas.greyseal.v1.Message		final_message is populated only on the last streamed response.

CreateConversationRequest

Field	Type	Label	Description
title	string		title is optional; left blank it can be auto-generated after the first exchange.
role_uuid	string		role_uuid optionally assigns a Role system prompt to this conversation.
resource_uuids	string	repeated	resource_uuids optionally scopes retrieval to specific resources.

CreateConversationResponse

Field	Type	Label	Description
data	schemas.greyseal.v1.Conversation

DeleteConversationRequest

Field	Type	Label	Description
uuid	string

DeleteConversationResponse

GetConversationRequest

Field	Type	Label	Description
uuid	string

GetConversationResponse

Field	Type	Label	Description
data	schemas.greyseal.v1.Conversation

ListConversationsRequest

Field	Type	Label	Description
count	int32	optional
cursor	string	optional

ListConversationsResponse

Field	Type	Label	Description
data	schemas.greyseal.v1.Conversation	repeated	Returns conversations without their messages for efficiency.
cursor	string
count	int32

SubmitFeedbackRequest

Field	Type	Label	Description
message_uuid	string
feedback	int32		feedback: -1 negative, 0 neutral, 1 positive.

SubmitFeedbackResponse

UpdateConversationRequest

Field	Type	Label	Description
uuid	string
title	string	optional	Fields that can be mutated after creation.
role_uuid	string	optional
resource_uuids	string	repeated

UpdateConversationResponse

Field	Type	Label	Description
data	schemas.greyseal.v1.Conversation

ConversationService

Method Name	Request Type	Response Type	Description
CreateConversation	CreateConversationRequest	CreateConversationResponse
GetConversation	GetConversationRequest	GetConversationResponse
ListConversations	ListConversationsRequest	ListConversationsResponse
UpdateConversation	UpdateConversationRequest	UpdateConversationResponse
DeleteConversation	DeleteConversationRequest	DeleteConversationResponse
Chat	ChatRequest	ChatResponse stream	Chat sends a user message and streams back the assistant response token by token.
SubmitFeedback	SubmitFeedbackRequest	SubmitFeedbackResponse	SubmitFeedback records user feedback on an assistant message.

Top

schemas/greyseal/v1/services/resource.proto

DeleteResourceRequest

Field	Type	Label	Description
uuid	string

DeleteResourceResponse

GetResourceRequest

Field	Type	Label	Description
uuid	string

GetResourceResponse

Field	Type	Label	Description
data	schemas.greyseal.v1.Resource

IngestResourceRequest

Field	Type	Label	Description
data	schemas.greyseal.v1.Resource

IngestResourceResponse

Field	Type	Label	Description
data	schemas.greyseal.v1.Resource

ListResourcesRequest

Field	Type	Label	Description
count	int32	optional
cursor	string	optional

ListResourcesResponse

Field	Type	Label
data	schemas.greyseal.v1.Resource	repeated
cursor	string
count	int32

ResourceService

Method Name	Request Type	Response Type	Description
IngestResource	IngestResourceRequest	IngestResourceResponse	IngestResource ingests a magpie resource, chunks it, and stores embeddings.
GetResource	GetResourceRequest	GetResourceResponse
ListResources	ListResourcesRequest	ListResourcesResponse
DeleteResource	DeleteResourceRequest	DeleteResourceResponse

Top

schemas/greyseal/v1/services/role.proto

CreateRoleRequest

Field	Type	Label	Description
data	schemas.greyseal.v1.Role

CreateRoleResponse

Field	Type	Label	Description
data	schemas.greyseal.v1.Role

DeleteRoleRequest

Field	Type	Label	Description
uuid	string

DeleteRoleResponse

GetRoleRequest

Field	Type	Label	Description
uuid	string

GetRoleResponse

Field	Type	Label	Description
data	schemas.greyseal.v1.Role

ListRolesRequest

Field	Type	Label	Description
count	int32	optional
cursor	string	optional

ListRolesResponse

Field	Type	Label
data	schemas.greyseal.v1.Role	repeated
cursor	string
count	int32

UpdateRoleRequest

Field	Type	Label	Description
uuid	string
data	schemas.greyseal.v1.Role

UpdateRoleResponse

Field	Type	Label	Description
data	schemas.greyseal.v1.Role

RoleService

Method Name	Request Type	Response Type
CreateRole	CreateRoleRequest	CreateRoleResponse
GetRole	GetRoleRequest	GetRoleResponse
ListRoles	ListRolesRequest	ListRolesResponse
UpdateRole	UpdateRoleRequest	UpdateRoleResponse
DeleteRole	DeleteRoleRequest	DeleteRoleResponse

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)