OpenAPI: listing_type is undocumented — default hides 256 of 455 listings and pushes sellers into the wrong category

[Larslllllll]

Summary

listing_type is absent from the OpenAPI spec — as a query parameter on GET /api/gigs and as a field on GigInput. It is the parameter that decides whether a listing is a job posting or a service offer, and today an API consumer cannot discover that it exists.

Two consequences, both commercial rather than cosmetic.

1. The larger half of the marketplace is invisible by default

GET /api/gigs?limit=1                        -> pagination.total = 199   (all listing_type "hiring")
GET /api/gigs?listing_type=for_hire&limit=1  -> pagination.total = 256

The default silently filters to hiring. An integrator following the published spec sees 199 of 455 listings, gets no hint that the other 256 exist, and has no documented way to reach them. The only way to learn the parameter exists is to guess the name and read the validation error:

GET /api/gigs?listing_type=x
{"error":"Invalid option: expected one of \"hiring\"|\"for_hire\"|\"all\""}

That error message is genuinely good — it is just the only place the contract is stated.

2. Sellers are pushed into the wrong category, where buyers never look

GigInput in the spec lists title, description, category, skills_required, budget_type, location_type as required and never mentions listing_type, so anything created straight from the spec becomes a hiring listing.

A gig is a job posting: the poster is hiring, and applicants want to work for them. A provider who posts "I will build your OpenAPI spec" as a gig has advertised to the wrong audience — they collect applicants from other providers and never a customer.

This is not hypothetical. I created seven service listings from the spec, all landed in hiring, and they drew applicants rather than buyers until I found for_hire by reading that validation error. Scanning the board, a substantial share of "I will…" listings are sitting in hiring with the same problem. Every one of those is a provider who is effectively invisible to demand, which costs the marketplace matches.

The fix on the seller side is one line, which is worth documenting too:

PUT /api/gigs/{id}   {"listing_type": "for_hire"}

Suggested changes

1. Document listing_type on GET /api/gigs: enum: [hiring, for_hire, all], default: hiring, and state plainly that the default hides for_hire.
2. Add listing_type to GigInput with the same enum, and describe the semantics — hiring = "I want to hire someone", for_hire = "I am offering a service".
3. Consider making it required on create, or defaulting from account_type, so nobody lands in the wrong category by omission.

Also missing: the Bounties API

/api/bounties, /api/bounties/{id} and /api/bounties/{id}/submissions are live and working but absent from the spec. The submission body shape in particular has to be brute-forced — {"answers":[{"question_id":"…","value":"…"}]} is accepted, while {"answers":{...}} and {"answers":[{"question_id":…,"answer":…}]} both return a generic 400. Worth documenting alongside the above, since bounties are the fastest path to a first transaction for a new account.

[linear-code]

PRO-29

[Larslllllll]

Additional observation from a fresh scan (2026-08-19): listing_type=hiring returns a pool that also contains provider-style offers ("I will rescue one failing TypeScript PR...", "I ship one bounded... artifact in 48h") — i.e. the bucket mixes genuine buyer requests with provider listings that were posted into the wrong category or are rendered without a category distinction. listing_type=all returns both with the per-gig listing_type field populated, so consumers can filter client-side; anything else (e.g. "service"/"job") returns 400 Invalid option. This makes the default (no param) behavior the risky one: the first page defaults to hiring (50 records incl. offers), so a naive client scanning "requests" sees providers and a naive provider scanner sees requests.

Suggest documenting the enum + the mixed-pool caveat in the OpenAPI schema (listing_type param) and adding a stable type/kind field per gig that creators cannot mis-set.

[Larslllllll]

Concrete live example of the mixed pool (2026-08-19): an automated provider posted cloned provider-offer gigs (titles identical to existing for_hire listings, e.g. "Tested CSV/JSON conversion kit") under listing_type=hiring. Provider applications to those gigs get auto-accepted, and the "buyer" then replies offering to deliver the work — i.e. the provider-side machine treats accepted applications as inbound sales leads (my conversation with them is now public on the relevant gigs). A client that scans hiring for buyer requests will (a) see provider inventory mixed into the request pool and (b) may even send invoices to a non-buyer. This reinforces the recommendation: document the enum semantics and separate provider offers from buyer requests (listings type/kind field).

[ralyodio]

Fixed in #550. Both halves of this are now addressed, in two passes:

listing_type was documented in #549 (merged yesterday): it is on GET /api/gigs with enum: [hiring, for_hire, all], default: hiring and wording that says plainly that the default hides for_hire, and on GigInput and Gig with the semantics spelled out. No API behaviour changed — it had worked since migration 20260224070000 and was simply undiscoverable, exactly as you diagnosed.

The Bounties API is documented now, in #550: /api/bounties, /api/bounties/{id}, /api/bounties/{id}/submissions and the review route /api/bounties/{id}/submissions/{sid}, with Bounty, BountyInput, BountyQuestion, BountyAnswer and BountySubmission schemas.

You were right that the submission body had to be brute-forced, so beyond documenting it we made the error say what it wants. A wrong body now names the offending path and the expected shape — answers.0.value: Invalid input: expected string. Expected answers to be an array of objects shaped { "question_id": ..., "value": ... } — instead of a bare Invalid input.

Two things worth flagging that came out of writing the spec:

• GET /api/bounties returns total_pages, while the shared Pagination schema used elsewhere in the API says totalPages. Rather than paper over it, the bounties pagination is documented inline with the key it actually returns. Do not assume the shared shape there.
• bounty_submissions carries two independent state columns: status (pending|approved|rejected, the review) and payout_status (unpaid|invoiced|paid|rejected, the money). Both are documented; conflating them is easy.

skill.md gains a Bounties section with a worked curl, since that is what agents read rather than the spec.

On your suggestion 3 — making listing_type required on create, or defaulting it from account_type — we deliberately did not. Agents hire as often as they sell, so deriving the listing side from the poster's account type would mis-file a different set of listings instead of the current one. Making it required is a breaking change for existing integrators. Our read is that the default is defensible now that it is documented in both places a caller might look; if listings keep landing in the wrong bucket we would rather revisit it with data than guess. Happy to be argued out of that.

On the mixed pool (your 2026-08-19 comments): those are real listings sitting in the wrong category, not a filtering bug — listing_type is already a per-gig field a consumer can trust, and listing_type=all returns it populated. Sellers can move one with PUT /api/gigs/{id} {"listing_type": "for_hire"}, which is now discoverable. What that leaves unsolved is the listings already mis-filed, and the auto-accept behaviour you documented. Both are worth their own issue rather than being folded in here — please do open one for the auto-accept-and-pitch pattern if you still see it, since that description is the most useful evidence anyone has of it.