API Reference

🦉 Owl · Go Temporal PostgreSQL Kafka

Protocol Documentation

Table of Contents

schemas/owl/v1/book.proto
- Book
schemas/owl/v1/paper.proto
- Paper
schemas/owl/v1/services/book.proto
schemas/owl/v1/services/paper.proto
Scalar Value Types

schemas/owl/v1/book.proto

Book

Book resource representing an uploaded or URL-fetched book

Field	Type	Label	Description
uuid	string		Unique identifier
title	string		Book title
authors	string	repeated	Authors
publisher	string		Publisher
publication_year	int32		Publication year
isbn	string		ISBN if available
format	string		File format (pdf, epub, mobi, azw3, etc.)
mime_type	string		MIME type
size_bytes	int64		File size in bytes
checksum	string		Content hash for deduplication (SHA-256)
storage_path	string		Storage location (bucket path)
original_filename	string		Original filename
tags	string	repeated	User-provided tags
notes	string		Notes or description
uploaded_at	google.protobuf.Timestamp		When uploaded
page_count	int32		Number of pages if available
language	string		Language (ISO 639-1 code)
source_url	string		Source URL if fetched from the web

schemas/owl/v1/paper.proto

Paper

Paper resource representing an academic paper

Field	Type	Label	Description
uuid	string		Unique identifier
title	string		Paper title
authors	string	repeated	Authors
abstract	string		Abstract
publication	string		Publication venue (journal, conference, etc.)
publication_year	int32		Publication year
doi	string		DOI (Digital Object Identifier) if available
arxiv_id	string		arXiv ID if applicable (e.g. "2301.07041")
source_url	string		Source URL where paper was fetched from
source_type	string		How the paper was acquired: DIRECT_UPLOAD, ARXIV, DOI, URL
format	string		File format (typically pdf)
mime_type	string		MIME type
size_bytes	int64		File size in bytes
checksum	string		Content hash for deduplication (SHA-256)
storage_path	string		Storage location (bucket path)
tags	string	repeated	User-provided tags
notes	string		Notes or description
uploaded_at	google.protobuf.Timestamp		When added to library
page_count	int32		Number of pages if available

schemas/owl/v1/services/book.proto

CreateBookRequest

Field	Type	Label	Description
data	schemas.owl.v1.Book

CreateBookResponse

Field	Type	Label	Description
data	schemas.owl.v1.Book

DeleteBookRequest

Field	Type	Label	Description
uuid	string

DeleteBookResponse

Field	Type	Label	Description
success	bool

GetBookRequest

Field	Type	Label	Description
uuid	string

GetBookResponse

Field	Type	Label	Description
data	schemas.owl.v1.Book

ListBooksRequest

Field	Type	Label	Description
count	int32	optional
cursor	string	optional

ListBooksResponse

Field	Type	Label	Description
data	schemas.owl.v1.Book	repeated
cursor	string
count	int32

UpdateBookRequest

Field	Type	Label	Description
uuid	string
data	schemas.owl.v1.Book

UpdateBookResponse

Field	Type	Label	Description
data	schemas.owl.v1.Book

BookService

Method Name	Request Type	Response Type	Description
ListBooks	ListBooksRequest	ListBooksResponse
GetBook	GetBookRequest	GetBookResponse
CreateBook	CreateBookRequest	CreateBookResponse
UpdateBook	UpdateBookRequest	UpdateBookResponse
DeleteBook	DeleteBookRequest	DeleteBookResponse

schemas/owl/v1/services/paper.proto

CreatePaperRequest

Field	Type	Label	Description
data	schemas.owl.v1.Paper

CreatePaperResponse

Field	Type	Label	Description
data	schemas.owl.v1.Paper

DeletePaperRequest

Field	Type	Label	Description
uuid	string

DeletePaperResponse

Field	Type	Label	Description
success	bool

GetIngestionStatusRequest

Field	Type	Label	Description
workflow_id	string

GetIngestionStatusResponse

Field	Type	Label	Description
status	GetIngestionStatusResponse.Status
paper_uuid	string		Populated on STATUS_COMPLETED or STATUS_DUPLICATE
error_message	string		Populated on STATUS_FAILED
current_step	string		Current activity being executed (from workflow metadata)

GetPaperRequest

Field	Type	Label	Description
uuid	string

GetPaperResponse

Field	Type	Label	Description
data	schemas.owl.v1.Paper

IngestPaperByURLRequest

IngestPaperByURL starts a Temporal workflow and returns immediately

Field	Type	Label	Description
url	string		URL to ingest (arXiv, DOI link, or direct PDF URL)
tags	string	repeated	Optional user tags to apply to the ingested paper
notes	string		Optional notes

IngestPaperByURLResponse

Field	Type	Label	Description
workflow_id	string		Temporal workflow ID — use with GetIngestionStatus to poll progress

ListPapersRequest

Field	Type	Label	Description
count	int32	optional
cursor	string	optional

ListPapersResponse

Field	Type	Label	Description
data	schemas.owl.v1.Paper	repeated
cursor	string
count	int32

UpdatePaperRequest

Field	Type	Label	Description
uuid	string
data	schemas.owl.v1.Paper

UpdatePaperResponse

Field	Type	Label	Description
data	schemas.owl.v1.Paper

GetIngestionStatusResponse.Status

Name	Number	Description
STATUS_UNSPECIFIED	0
STATUS_RUNNING	1
STATUS_COMPLETED	2
STATUS_FAILED	3
STATUS_DUPLICATE	4

PaperService

Method Name	Request Type	Response Type	Description
ListPapers	ListPapersRequest	ListPapersResponse
GetPaper	GetPaperRequest	GetPaperResponse
CreatePaper	CreatePaperRequest	CreatePaperResponse
UpdatePaper	UpdatePaperRequest	UpdatePaperResponse
DeletePaper	DeletePaperRequest	DeletePaperResponse
IngestPaperByURL	IngestPaperByURLRequest	IngestPaperByURLResponse	Temporal-backed async ingestion from URL (arXiv, DOI, direct link)
GetIngestionStatus	GetIngestionStatusRequest	GetIngestionStatusResponse	Query the status of an ongoing or completed ingestion workflow

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)