| 1 | openapi 3.0.3 |
| 2 | info |
| 3 | title: Intercom reference HTTP transport (profile reference-http-v1) |
| 4 | version: 1.0.0 |
| 5 | description: | |
| 6 | Transport profile for Intercom wire v1 — NOT the wire itself. |
| 7 | Canonical schemas: ../../schemas/v1/ |
| 8 | Reference implementation: intercom-service |
| 9 | servers |
| 10 | - url: http://127.0.0.1:5080 |
| 11 | paths |
| 12 | /health: |
| 13 | get: |
| 14 | summary: Health check |
| 15 | responses: |
| 16 | "200": |
| 17 | description: OK |
| 18 | /api/v1/auth/login: |
| 19 | get: |
| 20 | summary: Start OAuth (github | oidc) + PKCE |
| 21 | parameters: |
| 22 | - name: provider |
| 23 | in: query |
| 24 | required: true |
| 25 | schema: |
| 26 | type: string |
| 27 | enum: [github, oidc] |
| 28 | - name: team_id |
| 29 | in: query |
| 30 | required: true |
| 31 | schema: { type: string } |
| 32 | - name: redirect_uri |
| 33 | in: query |
| 34 | required: true |
| 35 | schema: { type: string, format: uri } |
| 36 | - name: code_challenge |
| 37 | in: query |
| 38 | schema: { type: string } |
| 39 | - name: code_challenge_method |
| 40 | in: query |
| 41 | schema: { type: string, enum: [S256] } |
| 42 | responses: |
| 43 | "302": |
| 44 | description: Redirect to IdP |
| 45 | /api/v1/auth/callback/github: |
| 46 | get: |
| 47 | summary: GitHub OAuth callback (server-side) |
| 48 | responses: |
| 49 | "302": |
| 50 | description: Redirect to client with tokens |
| 51 | /api/v1/auth/callback/oidc: |
| 52 | get: |
| 53 | summary: Generic OIDC callback |
| 54 | responses: |
| 55 | "302": |
| 56 | description: Redirect to client with tokens |
| 57 | /api/v1/auth/token: |
| 58 | post: |
| 59 | summary: Refresh access token |
| 60 | responses: |
| 61 | "200": |
| 62 | description: TokenResponse |
| 63 | /api/v1/auth/logout: |
| 64 | post: |
| 65 | summary: Revoke refresh token |
| 66 | security: [{ bearerAuth: [] }] |
| 67 | responses: |
| 68 | "200": |
| 69 | description: OK |
| 70 | /api/v1/auth/me: |
| 71 | get: |
| 72 | summary: Current member |
| 73 | security: [{ bearerAuth: [] }] |
| 74 | responses: |
| 75 | "200": |
| 76 | description: MeResponse |
| 77 | /api/v1/teams/{teamId}/topics: |
| 78 | get: |
| 79 | summary: List topics |
| 80 | security: [{ bearerAuth: [] }] |
| 81 | responses: |
| 82 | "200": |
| 83 | description: TopicDto[] |
| 84 | post: |
| 85 | summary: Create topic |
| 86 | security: [{ bearerAuth: [] }] |
| 87 | responses: |
| 88 | "200": |
| 89 | description: TopicDto |
| 90 | /api/v1/teams/{teamId}/topics/ensure: |
| 91 | post: |
| 92 | summary: Ensure topic by spine_key (e.g. thread_id) |
| 93 | security: [{ bearerAuth: [] }] |
| 94 | responses: |
| 95 | "200": |
| 96 | description: TopicDto |
| 97 | /api/v1/teams/{teamId}/events: |
| 98 | get: |
| 99 | summary: Catch-up all team events (after_seq) |
| 100 | security: [{ bearerAuth: [] }] |
| 101 | parameters: |
| 102 | - name: teamId |
| 103 | in: path |
| 104 | required: true |
| 105 | schema: { type: string } |
| 106 | - name: after_seq |
| 107 | in: query |
| 108 | schema: { type: integer, format: int64 } |
| 109 | - name: limit |
| 110 | in: query |
| 111 | schema: { type: integer } |
| 112 | responses: |
| 113 | "200": |
| 114 | description: TransportEventEnvelope[] |
| 115 | /api/v1/teams/{teamId}/stream: |
| 116 | get: |
| 117 | summary: SSE transport events (optional topic_id filter) |
| 118 | security: [{ bearerAuth: [] }] |
| 119 | responses: |
| 120 | "200": |
| 121 | description: text/event-stream |
| 122 | /api/v1/topics/{topicId}/events: |
| 123 | get: |
| 124 | summary: List events for topic |
| 125 | security: [{ bearerAuth: [] }] |
| 126 | responses: |
| 127 | "200": |
| 128 | description: TransportEventEnvelope[] |
| 129 | post: |
| 130 | summary: Append event (idempotent client_event_id) |
| 131 | security: [{ bearerAuth: [] }] |
| 132 | requestBody: |
| 133 | required: true |
| 134 | content: |
| 135 | application/json: |
| 136 | schema: |
| 137 | $ref: "#/components/schemas/AppendEventRequest" |
| 138 | responses: |
| 139 | "200": |
| 140 | description: TransportEventEnvelope |
| 141 | components |
| 142 | securitySchemes: |
| 143 | bearerAuth: |
| 144 | type: http |
| 145 | scheme: bearer |
| 146 | bearerFormat: JWT |
| 147 | schemas: |
| 148 | AppendEventRequest: |
| 149 | type: object |
| 150 | required: [schema_version, client_event_id, event_kind, payload] |
| 151 | properties: |
| 152 | schema_version: { type: integer } |
| 153 | client_event_id: { type: string } |
| 154 | occurred_at_utc: { type: string, format: date-time } |
| 155 | event_kind: { type: string } |
| 156 | sender: |
| 157 | type: object |
| 158 | payload: |
| 159 | type: object |
| 160 | description: See ../../schemas/v1/event-kinds.json |
| 161 | |