Skip to content

Commit 3fc839d

Browse files
author
stlc-bot
committed
docs(openapi): complete concise API reference metadata (#1329)
Stainless-Generated-From: e8b23b8b7a08bce62afc0ce0e4beb3bf68e3e0d6
1 parent 2ed83fb commit 3fc839d

16 files changed

Lines changed: 191 additions & 163 deletions

‎go.mod‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ require (
77
github.com/charmbracelet/bubbletea v1.3.6
88
github.com/charmbracelet/lipgloss v1.1.0
99
github.com/charmbracelet/x/term v0.2.1
10-
github.com/context-dot-dev/context-go-sdk/v2 v2.20.0
10+
github.com/context-dot-dev/context-go-sdk/v2 v2.21.0
1111
github.com/goccy/go-yaml v1.18.0
1212
github.com/itchyny/json2yaml v0.1.4
1313
github.com/muesli/reflow v0.3.0

‎go.sum‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,8 @@ github.com/charmbracelet/x/exp/golden v0.0.0-20241011142426-46044092ad91 h1:payR
1818
github.com/charmbracelet/x/exp/golden v0.0.0-20241011142426-46044092ad91/go.mod h1:wDlXFlCrmJ8J+swcL/MnGUuYnqgQdW9rhSD61oNMb6U=
1919
github.com/charmbracelet/x/term v0.2.1 h1:AQeHeLZ1OqSXhrAWpYUtZyX1T3zVxfpZuEQMIQaGIAQ=
2020
github.com/charmbracelet/x/term v0.2.1/go.mod h1:oQ4enTYFV7QN4m0i9mzHrViD7TQKvNEEkHUMCmsxdUg=
21-
github.com/context-dot-dev/context-go-sdk/v2 v2.20.0 h1:9T5bbQJuZXMq7rdRAoDAVuCKNFQnY+2btiKLBd+4pl4=
22-
github.com/context-dot-dev/context-go-sdk/v2 v2.20.0/go.mod h1:CvRANWLP0FHj5XyUwzEVX79ujdwr/2Jy375UVzKNQm8=
21+
github.com/context-dot-dev/context-go-sdk/v2 v2.21.0 h1:RyxgrE5I/5meO98tcfdtHh69ZaVLoDedsbHAmabPTHY=
22+
github.com/context-dot-dev/context-go-sdk/v2 v2.21.0/go.mod h1:CvRANWLP0FHj5XyUwzEVX79ujdwr/2Jy375UVzKNQm8=
2323
github.com/cpuguy83/go-md2man/v2 v2.0.2 h1:p1EgwI/C7NhT0JmVkwCD2ZBK8j4aeHQX2pMHHBfMQ6w=
2424
github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
2525
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=

‎pkg/cmd/batch.go‎

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,12 @@ import (
1616

1717
var batchRetrieve = cli.Command{
1818
Name: "retrieve",
19-
Usage: "Check progress, and get download links once the batch finishes.",
19+
Usage: "Get batch progress and result download links. Result files are deleted 7 days\nafter the batch finishes.",
2020
Suggest: true,
2121
Flags: []cli.Flag{
2222
&requestflag.Flag[string]{
2323
Name: "batch-id",
24-
Usage: "ID of the batch to retrieve or cancel.",
24+
Usage: "Batch ID.",
2525
Required: true,
2626
PathParam: "batch_id",
2727
},
@@ -32,7 +32,7 @@ var batchRetrieve = cli.Command{
3232

3333
var batchList = cli.Command{
3434
Name: "list",
35-
Usage: "List your batches from newest to oldest. Filter by status or continue with a\ncursor.",
35+
Usage: "List your batches, newest first, with optional filters.",
3636
Suggest: true,
3737
Flags: []cli.Flag{
3838
&requestflag.Flag[string]{
@@ -72,12 +72,12 @@ var batchList = cli.Command{
7272

7373
var batchDelete = cli.Command{
7474
Name: "delete",
75-
Usage: "Permanently delete a finished batch and its stored results. Active batches must\nsettle first.",
75+
Usage: "Permanently delete a finished batch and its results. Its webhook deliveries can\nno longer be retried.",
7676
Suggest: true,
7777
Flags: []cli.Flag{
7878
&requestflag.Flag[string]{
7979
Name: "batch-id",
80-
Usage: "ID of the batch to retrieve or cancel.",
80+
Usage: "Batch ID.",
8181
Required: true,
8282
PathParam: "batch_id",
8383
},
@@ -88,12 +88,12 @@ var batchDelete = cli.Command{
8888

8989
var batchCancel = cli.Command{
9090
Name: "cancel",
91-
Usage: "Stop a batch from starting new pages. In-progress pages finish, and unused\ncredits are refunded.",
91+
Usage: "Stop a batch from starting new pages. Pages already in progress finish before\nthe batch becomes cancelled.",
9292
Suggest: true,
9393
Flags: []cli.Flag{
9494
&requestflag.Flag[string]{
9595
Name: "batch-id",
96-
Usage: "ID of the batch to retrieve or cancel.",
96+
Usage: "Batch ID.",
9797
Required: true,
9898
PathParam: "batch_id",
9999
},
@@ -104,12 +104,12 @@ var batchCancel = cli.Command{
104104

105105
var batchGetResults = cli.Command{
106106
Name: "get-results",
107-
Usage: "Page through a finished batch's results as JSON instead of downloading the\nNDJSON files.",
107+
Usage: "Page through a finished batch’s results as JSON. Results remain available for 7\ndays.",
108108
Suggest: true,
109109
Flags: []cli.Flag{
110110
&requestflag.Flag[string]{
111111
Name: "batch-id",
112-
Usage: "ID of the batch to retrieve or cancel.",
112+
Usage: "Batch ID.",
113113
Required: true,
114114
PathParam: "batch_id",
115115
},
@@ -130,7 +130,7 @@ var batchGetResults = cli.Command{
130130

131131
var batchSubmit = requestflag.WithInnerFlags(cli.Command{
132132
Name: "submit",
133-
Usage: "Scrape 25K URLs or crawl large websites asynchronously.",
133+
Usage: "Scrape up to 25,000 URLs, or crawl a site, asynchronously. Poll the batch ID or\nreceive a webhook when it finishes.",
134134
Suggest: true,
135135
Flags: []cli.Flag{
136136
&requestflag.Flag[map[string]any]{
@@ -146,7 +146,7 @@ var batchSubmit = requestflag.WithInnerFlags(cli.Command{
146146
},
147147
&requestflag.Flag[map[string]any]{
148148
Name: "webhook",
149-
Usage: "Completion webhook settings. Cannot be combined with webhookUrl. Omitting retry preserves legacy delivery; retry: {} opts into durable retries.",
149+
Usage: "Where to send the batch's final-status event. Omit `retry` for one attempt; `{}` uses the default retry schedule.",
150150
BodyPath: "webhook",
151151
},
152152
&requestflag.Flag[string]{
@@ -156,7 +156,7 @@ var batchSubmit = requestflag.WithInnerFlags(cli.Command{
156156
},
157157
&requestflag.Flag[string]{
158158
Name: "idempotency-key",
159-
Usage: "Any string unique to this submission. Retries with the same key return the original batch.",
159+
Usage: "Unique key per submission. Retrying with the same key and body returns the original batch; a different body returns `409`.",
160160
HeaderPath: "Idempotency-Key",
161161
},
162162
},
@@ -166,6 +166,7 @@ var batchSubmit = requestflag.WithInnerFlags(cli.Command{
166166
"webhook": {
167167
&requestflag.InnerFlag[string]{
168168
Name: "webhook.url",
169+
Usage: "Public HTTP(S) URL that receives batch completion, failure, or cancellation events.",
169170
InnerField: "url",
170171
},
171172
&requestflag.InnerFlag[map[string]any]{

‎pkg/cmd/brand.go‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ import (
1616

1717
var brandRetrieve = requestflag.WithInnerFlags(cli.Command{
1818
Name: "retrieve",
19-
Usage: "Retrieve logos, backdrops, colors, industry, description, and more. Provide\nexactly one lookup identifier in the request body: a domain, company name, email\naddress, stock ticker, transaction descriptor, or direct URL. Note:\n`by_direct_url` fetches brand data only from the provided URL — not from the\nentire internet.",
19+
Usage: "Retrieve logos, colors, company details, and social links using one lookup\nidentifier. A direct URL limits extraction to that page.",
2020
Suggest: true,
2121
Flags: []cli.Flag{
2222
&requestflag.Flag[string]{
@@ -37,7 +37,7 @@ var brandRetrieve = requestflag.WithInnerFlags(cli.Command{
3737
},
3838
&requestflag.Flag[int64]{
3939
Name: "max-age-ms",
40-
Usage: "Maximum age in milliseconds for cached brand data before the API performs a hard refresh. Defaults to 3 months (7776000000 ms). Set to 0 to always perform a hard refresh. Negative values are clamped to 0; values above 1 year (31536000000 ms) are clamped to 1 year.",
40+
Usage: "Maximum age of cached brand data in ms. Defaults to 3 months; clamped to 0–1 year. `0` refreshes.",
4141
BodyPath: "maxAgeMs",
4242
},
4343
&requestflag.Flag[bool]{
@@ -47,12 +47,12 @@ var brandRetrieve = requestflag.WithInnerFlags(cli.Command{
4747
},
4848
&requestflag.Flag[[]string]{
4949
Name: "tag",
50-
Usage: "Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.",
50+
Usage: "Labels for filtering usage in the dashboard.",
5151
BodyPath: "tags",
5252
},
5353
&requestflag.Flag[map[string]any]{
5454
Name: "timeout-opts",
55-
Usage: "Optional request deadline and behavior on timeout. For GET requests, use timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded timeoutOpts object.",
55+
Usage: "Request deadline and what to return when it passes.",
5656
BodyPath: "timeoutOpts",
5757
},
5858
&requestflag.Flag[string]{
@@ -117,20 +117,20 @@ var brandRetrieve = requestflag.WithInnerFlags(cli.Command{
117117
"timeout-opts": {
118118
&requestflag.InnerFlag[int64]{
119119
Name: "timeout-opts.milliseconds",
120-
Usage: "Request deadline in milliseconds. Maximum: 300000 (5 minutes).",
120+
Usage: "Deadline in milliseconds.",
121121
InnerField: "milliseconds",
122122
},
123123
&requestflag.InnerFlag[string]{
124124
Name: "timeout-opts.behavior",
125-
Usage: `What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging credits. "return-partial" returns usable results collected so far; if none are available, the request still fails without charging credits. Partial results are not cached as complete results.`,
125+
Usage: `"fail" returns 408 at the deadline. "return-partial" returns available results; inspect the response’s partial flag.`,
126126
InnerField: "behavior",
127127
},
128128
},
129129
})
130130

131131
var brandSearch = cli.Command{
132132
Name: "search",
133-
Usage: "Search indexed brands by name or domain",
133+
Usage: "Find up to 10 brands by name or domain, ordered by popularity. Use the returned\ndomain to retrieve a full brand profile.",
134134
Suggest: true,
135135
Flags: []cli.Flag{
136136
&requestflag.Flag[string]{
@@ -153,7 +153,7 @@ var brandSearch = cli.Command{
153153
},
154154
&requestflag.Flag[[]string]{
155155
Name: "tag",
156-
Usage: "Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.",
156+
Usage: "Comma-separated labels for filtering usage, e.g. `production,team-alpha`.",
157157
QueryPath: "tags",
158158
},
159159
&requestflag.Flag[int64]{

‎pkg/cmd/industry.go‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ import (
1616

1717
var industryRetrieveNaics = requestflag.WithInnerFlags(cli.Command{
1818
Name: "retrieve-naics",
19-
Usage: "Classify any brand into 2022 NAICS industry codes from its domain or name.",
19+
Usage: "Classify a company into NAICS industry codes.",
2020
Suggest: true,
2121
Flags: []cli.Flag{
2222
&requestflag.Flag[string]{
@@ -39,17 +39,17 @@ var industryRetrieveNaics = requestflag.WithInnerFlags(cli.Command{
3939
},
4040
&requestflag.Flag[[]string]{
4141
Name: "tag",
42-
Usage: "Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.",
42+
Usage: "Comma-separated labels for filtering usage, e.g. `production,team-alpha`.",
4343
QueryPath: "tags",
4444
},
4545
&requestflag.Flag[map[string]any]{
4646
Name: "timeout-opts",
47-
Usage: "Optional request deadline and behavior on timeout. For GET requests, use timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded timeoutOpts object.",
47+
Usage: "Request deadline and what to return when it passes.",
4848
QueryPath: "timeoutOpts",
4949
},
5050
&requestflag.Flag[string]{
5151
Name: "zdr",
52-
Usage: "Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Asset uploads are skipped, so hosted image URLs are omitted. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.",
52+
Usage: "`enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR.",
5353
Default: "disabled",
5454
QueryPath: "zdr",
5555
},
@@ -60,20 +60,20 @@ var industryRetrieveNaics = requestflag.WithInnerFlags(cli.Command{
6060
"timeout-opts": {
6161
&requestflag.InnerFlag[int64]{
6262
Name: "timeout-opts.milliseconds",
63-
Usage: "Request deadline in milliseconds. Maximum: 300000 (5 minutes).",
63+
Usage: "Deadline in milliseconds.",
6464
InnerField: "milliseconds",
6565
},
6666
&requestflag.InnerFlag[string]{
6767
Name: "timeout-opts.behavior",
68-
Usage: `What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging credits. "return-partial" returns usable results collected so far; if none are available, the request still fails without charging credits. Partial results are not cached as complete results.`,
68+
Usage: `"fail" returns 408 at the deadline. "return-partial" returns available results; inspect the response’s partial flag.`,
6969
InnerField: "behavior",
7070
},
7171
},
7272
})
7373

7474
var industryRetrieveSic = requestflag.WithInnerFlags(cli.Command{
7575
Name: "retrieve-sic",
76-
Usage: "Classify any brand into Standard Industrial Classification (SIC) codes from its\ndomain or name. Choose between the original SIC system (`original_sic`) or the\nlatest SIC list maintained by the SEC (`latest_sec`).",
76+
Usage: "Classify a company into SIC industry codes.",
7777
Suggest: true,
7878
Flags: []cli.Flag{
7979
&requestflag.Flag[string]{
@@ -96,23 +96,23 @@ var industryRetrieveSic = requestflag.WithInnerFlags(cli.Command{
9696
},
9797
&requestflag.Flag[[]string]{
9898
Name: "tag",
99-
Usage: "Comma-separated tags for tracking request usage. Up to 20 tags, each 1-50 characters.",
99+
Usage: "Comma-separated labels for filtering usage, e.g. `production,team-alpha`.",
100100
QueryPath: "tags",
101101
},
102102
&requestflag.Flag[map[string]any]{
103103
Name: "timeout-opts",
104-
Usage: "Optional request deadline and behavior on timeout. For GET requests, use timeoutOpts[milliseconds]=30000&timeoutOpts[behavior]=fail or a JSON-encoded timeoutOpts object.",
104+
Usage: "Request deadline and what to return when it passes.",
105105
QueryPath: "timeoutOpts",
106106
},
107107
&requestflag.Flag[string]{
108108
Name: "type",
109-
Usage: "Which SIC dataset to classify against. `original_sic` uses the 1987 Standard Industrial Classification system; `latest_sec` uses the current SIC list as published by the SEC. Defaults to `original_sic`.",
109+
Usage: "SIC dataset: `original_sic` (1987) or `latest_sec` (current SEC list).",
110110
Default: "original_sic",
111111
QueryPath: "type",
112112
},
113113
&requestflag.Flag[string]{
114114
Name: "zdr",
115-
Usage: "Set to enabled to bypass shared caches and omit request and response content from retained usage logs. Asset uploads are skipped, so hosted image URLs are omitted. Requires zero data retention to be enabled for your organization (contact support@context.dev), otherwise the request fails with ZDR_NOT_ENABLED. Successful ZDR responses include X-Context-ZDR: true.",
115+
Usage: "`enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR.",
116116
Default: "disabled",
117117
QueryPath: "zdr",
118118
},
@@ -123,12 +123,12 @@ var industryRetrieveSic = requestflag.WithInnerFlags(cli.Command{
123123
"timeout-opts": {
124124
&requestflag.InnerFlag[int64]{
125125
Name: "timeout-opts.milliseconds",
126-
Usage: "Request deadline in milliseconds. Maximum: 300000 (5 minutes).",
126+
Usage: "Deadline in milliseconds.",
127127
InnerField: "milliseconds",
128128
},
129129
&requestflag.InnerFlag[string]{
130130
Name: "timeout-opts.behavior",
131-
Usage: `What to do at the deadline. "fail" returns 408 REQUEST_TIMEOUT without charging credits. "return-partial" returns usable results collected so far; if none are available, the request still fails without charging credits. Partial results are not cached as complete results.`,
131+
Usage: `"fail" returns 408 at the deadline. "return-partial" returns available results; inspect the response’s partial flag.`,
132132
InnerField: "behavior",
133133
},
134134
},

‎pkg/cmd/log.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ import (
1616

1717
var logsRetrieve = cli.Command{
1818
Name: "retrieve",
19-
Usage: "Get one logged API call, including its request input and response body.",
19+
Usage: "Retrieve a request’s metadata, retained input, and response.",
2020
Suggest: true,
2121
Flags: []cli.Flag{
2222
&requestflag.Flag[string]{
@@ -32,7 +32,7 @@ var logsRetrieve = cli.Command{
3232

3333
var logsList = cli.Command{
3434
Name: "list",
35-
Usage: "List your organization's API requests, newest first. Defaults to the last 24\nhours.",
35+
Usage: "List your organization’s request logs with filters and pagination. Logs also\ninclude batch settlements and monitor runs.",
3636
Suggest: true,
3737
Flags: []cli.Flag{
3838
&requestflag.Flag[string]{

0 commit comments

Comments
 (0)