104 lines
3.3 KiB
YAML
104 lines
3.3 KiB
YAML
|
openapi: "3.1.0"
|
||
|
|
info:
|
||
|
|
title: HelixForge Telegram Publishing
|
||
|
|
version: "R-1"
|
||
|
|
description: |
|
||
|
|
Publishes hall-of-helix entries to a Telegram channel.
|
||
|
|
|
||
|
|
The interface takes an entry as it was written and is responsible for
|
||
|
|
everything about how it becomes a Telegram post. A caller should never need
|
||
|
|
to know Telegram's constraints.
|
||
|
|
|
||
|
|
Publication is idempotent on entry_id: publishing the same entry twice
|
||
|
|
yields one publication. This matters because the caller is usually
|
||
|
|
automation that may be retried.
|
||
|
|
|
||
|
|
paths:
|
||
|
|
/v1/hall-entries:
|
||
|
|
post:
|
||
|
|
operationId: publishEntry
|
||
|
|
summary: Publish a hall-of-helix entry
|
||
|
|
requestBody:
|
||
|
|
required: true
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
type: object
|
||
|
|
required: [entry_id, title, body]
|
||
|
|
additionalProperties: false
|
||
|
|
properties:
|
||
|
|
entry_id:
|
||
|
|
type: string
|
||
|
|
minLength: 1
|
||
|
|
maxLength: 128
|
||
|
|
description: |
|
||
|
|
The hall entry's own id, from its frontmatter. Publication
|
||
|
|
is idempotent on this value.
|
||
|
|
title:
|
||
|
|
type: string
|
||
|
|
minLength: 1
|
||
|
|
maxLength: 256
|
||
|
|
body:
|
||
|
|
type: string
|
||
|
|
minLength: 1
|
||
|
|
description: |
|
||
|
|
The entry body as Markdown, frontmatter removed.
|
||
|
|
|
||
|
|
Deliberately unbounded. Telegram's 4096-character message
|
||
|
|
limit is this interface's problem, not the caller's, and a
|
||
|
|
maxLength here would push it back onto them.
|
||
|
|
display_name:
|
||
|
|
type: string
|
||
|
|
maxLength: 128
|
||
|
|
worker_kind:
|
||
|
|
type: string
|
||
|
|
enum: [human, agent-session]
|
||
|
|
recorded_at:
|
||
|
|
type: string
|
||
|
|
format: date
|
||
|
|
source_url:
|
||
|
|
type: string
|
||
|
|
description: Canonical location of the entry in hall-of-helix.
|
||
|
|
responses:
|
||
|
|
"201":
|
||
|
|
description: Published
|
||
|
|
"200":
|
||
|
|
description: Already published; the existing publication is returned
|
||
|
|
"400":
|
||
|
|
description: The entry cannot be published faithfully
|
||
|
|
"502":
|
||
|
|
description: Telegram was unreachable or refused the message
|
||
|
|
|
||
|
|
get:
|
||
|
|
operationId: listPublications
|
||
|
|
summary: List publications, newest first
|
||
|
|
parameters:
|
||
|
|
- name: limit
|
||
|
|
in: query
|
||
|
|
required: false
|
||
|
|
schema: {type: integer, minimum: 1, maximum: 100}
|
||
|
|
- name: state
|
||
|
|
in: query
|
||
|
|
required: false
|
||
|
|
schema:
|
||
|
|
type: string
|
||
|
|
enum: [pending, published, failed, superseded]
|
||
|
|
responses:
|
||
|
|
"200":
|
||
|
|
description: Publications
|
||
|
|
|
||
|
|
/v1/hall-entries/{entry_id}:
|
||
|
|
get:
|
||
|
|
operationId: getPublication
|
||
|
|
summary: Publication state for one entry
|
||
|
|
parameters:
|
||
|
|
- name: entry_id
|
||
|
|
in: path
|
||
|
|
required: true
|
||
|
|
schema: {type: string, minLength: 1}
|
||
|
|
responses:
|
||
|
|
"200":
|
||
|
|
description: Publication state
|
||
|
|
"404":
|
||
|
|
description: This entry has not been published
|