OpenVibeCoding/docs/api/index.html at 5de7f4d6a03d3796b8a7119127b4e20caa7b22ae · xiaojiou176-open/OpenVibeCoding · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>CortexPilot | API and contract quickstart</title>
    <meta
      name="description"
      content="API and contract quickstart for CortexPilot: OpenAPI entrypoints, thin frontend API client, contract-facing types, and the shortest adoption path for Codex, Claude Code, and OpenClaw teams."
    />
    <meta
      name="keywords"
      content="CortexPilot API, CortexPilot OpenAPI, frontend API client, contract types, Codex API workflow, Claude Code API workflow, OpenClaw builder path"
    />
    <link rel="canonical" href="https://xiaojiou176-open.github.io/CortexPilot-public/api/" />
    <meta property="og:title" content="CortexPilot | API and contract quickstart" />
    <meta
      property="og:description"
      content="API and contract quickstart for CortexPilot across OpenAPI, thin frontend API helpers, and contract-facing types."
    />
    <meta property="og:url" content="https://xiaojiou176-open.github.io/CortexPilot-public/api/" />
    <meta property="og:type" content="article" />
    <meta property="og:image" content="../assets/storefront/social-preview-1280x640.png" />
    <meta name="twitter:card" content="summary_large_image" />
    <meta name="twitter:title" content="CortexPilot | API and contract quickstart" />
    <meta
      name="twitter:description"
      content="OpenAPI, frontend API client, and contract-facing type quickstart for CortexPilot."
    />
    <meta name="twitter:image" content="../assets/storefront/social-preview-1280x640.png" />
    <script type="application/ld+json">
      {
        "@context": "https://schema.org",
        "@type": "TechArticle",
        "headline": "CortexPilot API and contract quickstart",
        "url": "https://xiaojiou176-open.github.io/CortexPilot-public/api/",
        "description": "API and contract quickstart for CortexPilot across OpenAPI, thin frontend API helpers, and contract-facing types."
      }
    </script>
    <script type="application/ld+json">
      {
        "@context": "https://schema.org",
        "@type": "FAQPage",
        "mainEntity": [
          {
            "@type": "Question",
            "name": "Is CortexPilot a full SDK platform today?",
            "acceptedAnswer": {
              "@type": "Answer",
              "text": "No. CortexPilot already exposes a useful API and contract edge, but the public builder story is still a thin client plus generated contract package plus shared presentation substrate, not a full SDK platform."
            }
          },
          {
            "@type": "Question",
            "name": "Who should open the API quickstart first?",
            "acceptedAnswer": {
              "@type": "Answer",
              "text": "Teams should start here when their first question is about the HTTP contract, route/type boundaries, thin client helpers, or builder bootstrap rather than protocol-level MCP inspection."
            }
          },
          {
            "@type": "Question",
            "name": "Do guarded operator-only routes change the public builder promise?",
            "acceptedAnswer": {
              "@type": "Answer",
              "text": "No. Role-config preview/apply and queue preview/cancel remain guarded operator HTTP add-ons. They do not upgrade the public story into hosted mutation, public write-capable MCP, or a full SDK platform."
            }
          }
        ]
      }
    </script>
    <style>
      :root {
        color-scheme: light;
        --bg: #f6f0e9;
        --panel: #fffaf3;
        --ink: #17232c;
        --muted: #536370;
        --line: rgba(23, 35, 44, 0.12);
        --accent: #8b4513;
        --accent-soft: rgba(139, 69, 19, 0.1);
        --accent-alt: #155e75;
        --accent-alt-soft: rgba(21, 94, 117, 0.1);
        --warn: #92400e;
        --warn-soft: rgba(146, 64, 14, 0.1);
        --shadow: 0 22px 52px rgba(23, 35, 44, 0.1);
      }

      * { box-sizing: border-box; }

      body {
        margin: 0;
        background:
          radial-gradient(circle at top right, rgba(139, 69, 19, 0.08), transparent 28%),
          radial-gradient(circle at top left, rgba(21, 94, 117, 0.08), transparent 24%),
          linear-gradient(180deg, #faf5ed 0%, #efe6da 100%);
        color: var(--ink);
        font: 16px/1.65 "Inter", "Segoe UI", system-ui, sans-serif;
      }

      main {
        max-width: 1080px;
        margin: 0 auto;
        padding: 40px 20px 72px;
      }

      a { color: var(--accent-alt); }
      a:hover { color: #0f4d60; }

      .hero,
      .section,
      .table-shell {
        background: var(--panel);
        border: 1px solid var(--line);
        border-radius: 28px;
        box-shadow: var(--shadow);
      }

      .hero,
      .section {
        padding: 28px;
      }

      .section { margin-top: 24px; }

      .eyebrow,
      .badge {
        display: inline-flex;
        width: fit-content;
        padding: 7px 12px;
        border-radius: 999px;
        font-size: 13px;
        font-weight: 700;
      }

      .eyebrow {
        background: rgba(23, 35, 44, 0.08);
        color: var(--muted);
      }

      .badge.primary { background: var(--accent-soft); color: var(--accent); }
      .badge.protocol { background: var(--accent-alt-soft); color: var(--accent-alt); }
      .badge.warn { background: var(--warn-soft); color: var(--warn); }

      h1, h2, h3 { margin: 0; line-height: 1.15; }
      h1 { font-size: clamp(2.4rem, 4vw, 3.8rem); max-width: 12ch; }
      h2 { font-size: 1.7rem; margin-bottom: 12px; }
      p, li, td { color: var(--muted); }
      .lede { font-size: 1.08rem; max-width: 78ch; }

      .mini-nav,
      .actions {
        display: flex;
        flex-wrap: wrap;
        gap: 12px;
      }

      .button {
        display: inline-flex;
        align-items: center;
        justify-content: center;
        padding: 12px 16px;
        border-radius: 999px;
        text-decoration: none;
        font-weight: 600;
      }

      .button.primary { background: var(--accent); color: white; }
      .button.secondary {
        border: 1px solid var(--line);
        background: white;
        color: var(--ink);
      }

      .grid {
        display: grid;
        grid-template-columns: repeat(auto-fit, minmax(230px, 1fr));
        gap: 16px;
      }

      .card {
        border: 1px solid var(--line);
        border-radius: 22px;
        background: white;
        padding: 18px;
      }

      .table-shell {
        margin-top: 24px;
        overflow: hidden;
      }

      table {
        width: 100%;
        border-collapse: collapse;
      }

      th, td {
        padding: 14px 16px;
        border-bottom: 1px solid var(--line);
        text-align: left;
        vertical-align: top;
      }

      th {
        font-size: 13px;
        letter-spacing: 0.03em;
        text-transform: uppercase;
        background: rgba(23, 35, 44, 0.04);
      }

      tr:last-child td { border-bottom: none; }

      code {
        background: rgba(23, 35, 44, 0.06);
        border-radius: 6px;
        padding: 2px 6px;
        font-family: "SFMono-Regular", Menlo, monospace;
      }

      pre {
        overflow-x: auto;
        padding: 16px;
        border-radius: 18px;
        background: #fbf1e8;
      }
    </style>
  </head>
  <body>
    <main>
      <section class="hero">
        <span class="eyebrow">HTTP and package edge</span>
        <nav class="mini-nav" aria-label="Top navigation">
          <a href="../">Back to the public landing page</a>
          <a href="../compatibility/">Compatibility matrix</a>
          <a href="../agent-starters/">Agent starter kits</a>
          <a href="../ai-surfaces/">AI + MCP + API surfaces</a>
          <a href="../integrations/">Integration guide</a>
          <a href="../builders/">Builder quickstart</a>
          <a href="../mcp/">Read-only MCP quickstart</a>
        </nav>
        <h1>API and contract quickstart.</h1>
        <p class="lede">
          CortexPilot is not a full SDK platform today, but it already exposes a useful API and contract edge for dashboard, desktop, and custom frontend consumers.
          This page is the shortest truthful map when your first question is about <strong>HTTP routes, type boundaries, thin client helpers, or builder bootstrap</strong>.
        </p>
        <p class="lede">
          If your first question is instead about protocol-level inspection, read-only MCP, or how a coding-agent team should adopt the system truthfully, this page should route you to the better next click instead of making you reverse-engineer the package story from source.
        </p>
        <p class="lede">
          Current package boundary: <code>@cortexpilot/frontend-api-client</code> and
          <code>@cortexpilot/frontend-api-contract</code> now carry publish-ready metadata,
          but no public package release is live yet. The truthful external adoption path
          today is still clone-and-reuse or vendor-and-adapt, while
          <code>@cortexpilot/frontend-shared</code> remains a repo-owned presentation
          substrate rather than a standalone registry story.
        </p>
        <div class="actions">
          <a class="button primary" href="#choose-the-shortest-starting-point">Open the builder path</a>
          <a class="button secondary" href="../compatibility/">Open compatibility matrix</a>
          <a class="button secondary" href="../agent-starters/">Open agent starter kits</a>
          <a class="button secondary" href="../mcp/">Open MCP quickstart</a>
          <a class="button secondary" href="../builders/">Open builder quickstart</a>
          <a class="button secondary" href="../integrations/">Open integration guide</a>
        </div>
      </section>

      <section class="section" id="choose-the-shortest-starting-point">
        <h2>Choose the shortest starting point</h2>
        <div class="table-shell">
          <table>
            <thead>
              <tr>
                <th>My first question</th>
                <th>Start here</th>
                <th>Why</th>
              </tr>
            </thead>
            <tbody>
              <tr>
                <td>I need the raw HTTP contract</td>
                <td>This page</td>
                <td>Stay here when your team needs OpenAPI, route/query boundaries, and the package edge first.</td>
              </tr>
              <tr>
                <td>I need the protocol boundary first</td>
                <td><a href="../mcp/">Read-only MCP quickstart</a></td>
                <td>Jump to MCP when the main question is machine-readable inspection rather than package import.</td>
              </tr>
              <tr>
                <td>I need the best next click for Codex / Claude Code / OpenClaw / skills / builders</td>
                <td><a href="../compatibility/">Compatibility matrix</a></td>
                <td>Use it when the team still needs the adoption ladder answer before deeper onboarding.</td>
              </tr>
              <tr>
                <td>I need repo-owned builder packages</td>
                <td><a href="../builders/">Builder quickstart</a></td>
                <td>Use it when you already know you want the workspace-local package layer rather than the protocol or proof-first story.</td>
              </tr>
            </tbody>
          </table>
        </div>
      </section>

      <section class="section">
        <h2>What builders can do today</h2>
        <div class="grid">
          <article class="card">
            <span class="badge primary">OpenAPI</span>
            <h3>Machine-facing contract</h3>
            <p>Use the public OpenAPI document when you want the raw HTTP route contract before client or UI sugar.</p>
            <p><a href="https://github.com/xiaojiou176-open/CortexPilot-public/blob/main/docs/api/openapi.cortexpilot.json">Open OpenAPI document</a></p>
          </article>
          <article class="card">
            <span class="badge primary">Client</span>
            <h3>Thin frontend API helpers</h3>
            <p>Use <code>@cortexpilot/frontend-api-client</code> when you are working inside a clone, shared workspace, or vendored internal package path and want convenience helpers over runs, Workflow Cases, approvals, and command-tower reads.</p>
            <p><a href="https://github.com/xiaojiou176-open/CortexPilot-public/blob/main/packages/frontend-api-client/README.md">Open client README</a></p>
          </article>
          <article class="card">
            <span class="badge primary">Contract</span>
            <h3>Generated type boundary</h3>
            <p>Use <code>@cortexpilot/frontend-api-contract</code> when you are inside the same repo or a vendored workspace copy and want route/query/type boundaries without importing backend modules.</p>
            <p><a href="https://github.com/xiaojiou176-open/CortexPilot-public/blob/main/packages/frontend-api-contract/docs/README.md">Open contract guide</a></p>
          </article>
          <article class="card">
            <span class="badge primary">Shared substrate</span>
            <h3>Locale and presentation reuse</h3>
            <p>Use <code>@cortexpilot/frontend-shared</code> when you are reusing CortexPilot from a clone or vendored workspace and need shared copy, locale helpers, and status presentation across dashboard and desktop surfaces.</p>
            <p><a href="https://github.com/xiaojiou176-open/CortexPilot-public/blob/main/packages/frontend-shared/README.md">Open shared README</a></p>
          </article>
        </div>
      </section>

      <section class="section">
        <h2>Repo-owned starter path</h2>
        <p>
          Teams that want the shortest repo-owned starter should begin with <code>createControlPlaneStarter(...)</code> on top of the client when they are working inside a clone or vendored workspace copy, because it bundles the current overview + agents + contracts + role config bootstrap path without implying a hosted SDK platform.
        </p>
        <p>
          The repo-owned <a href="https://github.com/xiaojiou176-open/CortexPilot-public/blob/main/packages/frontend-api-client/examples/control_plane_starter.local.mjs">starter example</a> shows the same bootstrap + preview path as runnable code instead of leaving builders to reconstruct it from prose alone.
        </p>
        <pre><code>node packages/frontend-api-client/examples/control_plane_starter.local.mjs \
  --base-url http://127.0.0.1:10000 \
  --role WORKER \
  --mutation-role TECH_LEAD \
  --preview-provider cliproxyapi \
  --preview-model gpt-5.4</code></pre>
      </section>

      <section class="section">
        <h2>Guarded operator-only add-ons</h2>
        <p>
          A few extra HTTP surfaces exist for trusted repo operators, but they are intentionally outside the default external builder promise.
        </p>
        <ul>
          <li><code>/api/agents/roles/{role}/config/preview</code> and <code>/apply</code> stay repo-owned role-default control-plane paths.</li>
          <li><code>/api/queue/from-run/{run_id}/preview</code> and <code>/api/queue/{queue_id}/cancel</code> stay queue-only operator routes for trusted maintainers.</li>
          <li>These guarded routes do <strong>not</strong> upgrade the public story into hosted mutation, public write-capable MCP, or a full SDK platform.</li>
        </ul>
      </section>

      <section class="section">
        <h2>Current boundary</h2>
        <div class="grid">
          <article class="card">
            <span class="badge warn">Boundary</span>
            <h3>Builder edge, not full SDK</h3>
            <p>This is a useful builder edge today, but it is still not a full SDK platform.</p>
          </article>
          <article class="card">
            <span class="badge warn">Boundary</span>
            <h3>Read-oriented story</h3>
            <p>The public builder story is still read-oriented and repo-owned, not a hosted operator service.</p>
          </article>
          <article class="card">
            <span class="badge warn">Boundary</span>
            <h3>Guarded add-ons stay guarded</h3>
            <p>Role-config preview/apply and queue preview/cancel stay operator-only helpers, not the primary external onboarding promise.</p>
          </article>
          <article class="card">
            <span class="badge warn">Boundary</span>
            <h3>Publish-ready, not published</h3>
            <p>The thin client and contract package are ready for a future public release, but no npm publication is live yet, so the truthful install path is still clone/workspace reuse or vendor copy rather than <code>npm install</code>.</p>
          </article>
          <article class="card">
            <span class="badge warn">Boundary</span>
            <h3>Shared stays repo-owned</h3>
            <p><code>@cortexpilot/frontend-shared</code> remains the repo-owned presentation substrate for dashboard and desktop surfaces, not a standalone distribution unit today.</p>
          </article>
        </div>
      </section>

      <section class="section">
        <h2>Minimal onboarding order</h2>
        <ol>
          <li>Read the OpenAPI document if you need the raw HTTP contract.</li>
          <li>Use the <a href="../compatibility/">compatibility matrix</a> if you need the best next click for Codex / Claude Code / OpenClaw / skills / builders before deeper onboarding.</li>
          <li>Use the thin client package when you want convenience helpers over that contract.</li>
          <li>Use contract-facing types when you want typed route/query boundaries without importing backend modules.</li>
          <li>Pair the result with the <a href="../builders/">builder quickstart</a> so package-level adoption stays aligned with the current MCP/API story.</li>
        </ol>
      </section>
    </main>
  </body>
</html>