{"openapi":"3.1.0","info":{"title":"GitDex API","version":"1.0.0","description":"Software demand & solution network. Reads are public; writes need a signed-in account, an Idempotency-Key header, and (for publishing operations) `confirmed: true` after the user approved the preview returned by a call without it. GitDex runs no AI model. Agent guide: https://gitdex.ai/ai/guide.md"},"servers":[{"url":"https://gitdex.ai/api/v1"}],"paths":{"/software":{"get":{"operationId":"search_software","summary":"Search software","description":"Search the GitDex software directory by keyword and static filters. USE WHEN the user is looking for software, or before submitting software to check for an existing record. NEEDS a short keyword query (product type, key capability), optionally platforms and pricing. Matching is plain keyword matching, not semantic: send the distinctive nouns, and try a second phrasing before concluding nothing fits. Records are in English, Chinese or both, and both versions are searched: if the user's language finds nothing, try the keywords in the other one. NO side effects; public, no sign-in. An empty result only means nothing has been submitted to GitDex yet, never that such software does not exist. Searching never implies the user wants to publish a request.","tags":["software"],"security":[],"parameters":[{"name":"q","in":"query","required":false,"description":"Keywords, e.g. 'offline notes markdown'.","schema":{"type":"string"}},{"name":"platforms","in":"query","required":false,"description":"Match software available on any of these platforms, e.g. ['ios','web','macos','windows','linux','android','cli'].","schema":{"type":"string","description":"Comma-separated list."}},{"name":"pricing","in":"query","required":false,"description":"Match any of these pricing types.","schema":{"type":"string","description":"Comma-separated list."}},{"name":"category","in":"query","required":false,"description":"Exact category tag.","schema":{"type":"string"}},{"name":"submitted_by","in":"query","required":false,"description":"Only software submitted by this user: the `submitted_by.id` of a record. Lists one author's software.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"'solved' puts first the software accepted by the most requesters (accepted_solution_count). That counts other people's needs, so still compare capabilities with this user's must-haves.","schema":{"type":"string","enum":["relevance","newest","updated","name","solved"],"default":"relevance"}},{"name":"limit","in":"query","required":false,"description":"Page size (max 50).","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","required":false,"description":"Items to skip; use next_offset from the previous page.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"submit_software","summary":"Submit software to the directory","description":"Add a software record to the public directory. USE WHEN a creator (or a user) wants to list existing or newly built software and search_software found no record for it. NEEDS name, the official site or repository URL, and a factual description; add capabilities, platforms, pricing_type and sources when known. Write the text in the user's language and add the other language (English or Chinese) in `translations`, so the listing is published in both. Add icon_url and screenshots when the software has public images of its own; never invent, generate or borrow images. Leave unknown fields out or 'unknown'; never invent pricing, capabilities or verification. How the software was built (AI or not) is irrelevant. Submitting does not make the user the owner of the software. SIDE EFFECT: creates a public record with review_status 'unreviewed'. REQUIRES sign-in. FLOW: call WITHOUT confirmed to get the preview, show it (both language versions and the images), get explicit approval, then call with confirmed=true and the same idempotency_key. Recovery: DUPLICATE_CANDIDATE returns the existing record; use its software_id instead.","tags":["software"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200},"description":"Unique key for this intended write (e.g. a UUID). Reuse the SAME key when retrying the same write so it is applied once."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Product name.","minLength":2,"maxLength":120},"url":{"type":"string","description":"Official website or repository URL (public http/https)."},"repository_url":{"type":"string","description":"Source repository URL, if any (GitHub, GitLab, Codeberg, Bitbucket)."},"app_store_url":{"type":"string","description":"The product's own App Store listing, if it has one: https://apps.apple.com/<country>/app/<name>/id<number>. Shown as the App Store badge. Only this app's listing; leave empty when unsure."},"google_play_url":{"type":"string","description":"The product's own Google Play listing, if it has one: https://play.google.com/store/apps/details?id=<package>. Shown as the Google Play badge. Only this app's listing; leave empty when unsure."},"description":{"type":"string","description":"Factual description of what the software does.","minLength":10,"maxLength":2000},"capabilities":{"type":"array","items":{"type":"string"},"description":"Concrete capabilities, one per item."},"platforms":{"type":"array","items":{"type":"string"},"description":"Platforms it runs on, e.g. ['ios','web']."},"pricing_type":{"type":"string","enum":["free","freemium","paid","subscription","open_source","unknown"],"default":"unknown"},"pricing_notes":{"type":"string","description":"Pricing details and limits in plain words."},"license":{"type":"string","description":"License, if applicable, e.g. 'MIT'."},"category":{"type":"array","items":{"type":"string"},"description":"Category tags."},"icon_url":{"type":"string","description":"Public https URL of the product's own icon or logo (square works best), e.g. from its site, repository or store listing. Shown like an app icon. GitDex links to the image; it does not copy it."},"screenshots":{"type":"array","items":{"type":"string"},"maxItems":8,"description":"Up to 8 public https image URLs of real screenshots of this software, in display order. Use images the creator publishes; leave empty when there are none. These are the screenshots for the record's own language and the fallback for every reader; if the product also has screenshots in the other language, put those in translations.<lang>.screenshots."},"language":{"type":"string","enum":["en","zh"],"description":"Language the text fields of this call are written in: 'en' or 'zh'. Write in the user's own language. Detected from the text when omitted."},"translations":{"type":"object","description":"The same text in the other language, keyed by language code: { \"zh\": { ... } } for a record written in English, { \"en\": { ... } } for one written in Chinese. ALWAYS provide it unless the user declines: GitDex shows each visitor one language. Translate every one of these fields that the original has: description, capabilities, pricing_notes. Lists keep the same number of items in the same order. Translate faithfully; add no claims and drop no limits. Never mix two languages inside one field.","properties":{"en":{"type":"object","properties":{"description":{"type":"string","maxLength":2000},"capabilities":{"type":"array","items":{"type":"string"},"description":"Same number of items as the original, in the same order."},"pricing_notes":{"type":"string","maxLength":500},"screenshots":{"type":"array","items":{"type":"string"},"maxItems":8,"description":"OPTIONAL. Public https URLs of screenshots that show the software in THIS language. Only when such screenshots exist; leave out otherwise and readers of this language see the record's own screenshots."}},"additionalProperties":false},"zh":{"type":"object","properties":{"description":{"type":"string","maxLength":2000},"capabilities":{"type":"array","items":{"type":"string"},"description":"Same number of items as the original, in the same order."},"pricing_notes":{"type":"string","maxLength":500},"screenshots":{"type":"array","items":{"type":"string"},"maxItems":8,"description":"OPTIONAL. Public https URLs of screenshots that show the software in THIS language. Only when such screenshots exist; leave out otherwise and readers of this language see the record's own screenshots."}},"additionalProperties":false}},"additionalProperties":false},"sources":{"type":"array","description":"Where the listed facts come from.","items":{"type":"object","properties":{"url":{"type":"string","description":"Public http(s) URL of the source."},"claim":{"type":"string","description":"What this source supports, in one sentence."},"source_type":{"type":"string","enum":["official_site","repository","documentation","store_listing","review","other"]},"verification_level":{"type":"string","enum":["claimed","documented","unknown"],"description":"claimed = the vendor says so; documented = stated in official docs/repo you actually read; unknown = not checked. 'tested' cannot be asserted by a submitter."}},"required":["url"]}},"confirmed":{"type":"boolean","description":"Set true ONLY after the user has seen the exact preview returned by a call without it and explicitly approved. Never set it on your own initiative."}},"required":["name","url","description"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_CANDIDATE / CONFLICT / INVALID_STATE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/software/{software_id}":{"get":{"operationId":"get_software","summary":"Get software details","description":"Get one software record with its evidence and the requests it has been proposed for. USE WHEN you need details, sources or verification status for a software_id (or slug) from search results. NO side effects; public. Text fields come in the record's own `language`; `translations` holds the other language (English/Chinese) when the submitter provided it, so answer from the version in the user's language. Report unknown fields as unknown; 'unreviewed' records and 'claimed' evidence are not independently verified. Recovery: NOT_FOUND means the ID is wrong; search again.","tags":["software"],"security":[],"parameters":[{"name":"software_id","in":"path","required":true,"schema":{"type":"string"},"description":"Software ID (sw_...) or slug."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"update_software","summary":"Edit my software record","description":"Change a software record the signed-in user submitted: name, description, capabilities, platforms, pricing, license, category, icon, screenshots, store listings or sources. USE WHEN the submitter asks to correct or update their listing (new version, new price, better screenshots). The site and repository URLs identify the record and cannot be changed. SIDE EFFECT: publishes a new version; a 'reviewed' record goes back to 'unreviewed' because no moderator has seen the new text. REQUIRES sign-in as the submitter. Send only the fields that change; everything else stays as it is. If any text field changes, the old translation no longer matches: send `translations` again for the other language or it is dropped. NOTHING IS ERASED: the version being replaced stays publicly visible in the record's history, so an edit cannot be used to hide what was published (to take down private or unlawful text, tell the user to report the record). FLOW: call WITHOUT confirmed to get the preview showing the new values next to the ones they replace, show it, get explicit approval, then call with confirmed=true and the same idempotency_key. Recovery: FORBIDDEN means someone else submitted it, do not retry; INVALID_STATE means nothing would change.","tags":["software"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"software_id","in":"path","required":true,"schema":{"type":"string"},"description":"Software ID (sw_...) or slug."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200},"description":"Unique key for this intended write (e.g. a UUID). Reuse the SAME key when retrying the same write so it is applied once."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Product name.","minLength":2,"maxLength":120},"description":{"type":"string","description":"Factual description of what the software does.","minLength":10,"maxLength":2000},"capabilities":{"type":"array","items":{"type":"string"},"description":"Concrete capabilities, one per item. Replaces the whole list."},"platforms":{"type":"array","items":{"type":"string"},"description":"Platforms it runs on. Replaces the whole list."},"pricing_type":{"type":"string","enum":["free","freemium","paid","subscription","open_source","unknown"]},"pricing_notes":{"type":["string","null"],"description":"Pricing details in plain words; null removes them."},"license":{"type":["string","null"],"description":"License; null removes it."},"category":{"type":"array","items":{"type":"string"},"description":"Category tags. Replaces the whole list."},"icon_url":{"type":["string","null"],"description":"Public https URL of the product's own icon; null removes it."},"app_store_url":{"type":["string","null"],"description":"The product's own App Store listing (https://apps.apple.com/<country>/app/<name>/id<number>); null removes it."},"google_play_url":{"type":["string","null"],"description":"The product's own Google Play listing (https://play.google.com/store/apps/details?id=<package>); null removes it."},"screenshots":{"type":"array","items":{"type":"string"},"maxItems":8,"description":"Public https image URLs in display order. Replaces the whole list; [] removes all."},"sources":{"type":"array","description":"Where the listed facts come from. Send it whenever the edit changes a fact (price, capability, license). Replaces the sources this user gave before; [] removes them.","items":{"type":"object","properties":{"url":{"type":"string","description":"Public http(s) URL of the source."},"claim":{"type":"string","description":"What this source supports, in one sentence."},"source_type":{"type":"string","enum":["official_site","repository","documentation","store_listing","review","other"]},"verification_level":{"type":"string","enum":["claimed","documented","unknown"],"description":"claimed = the vendor says so; documented = stated in official docs/repo you actually read; unknown = not checked. 'tested' cannot be asserted by a submitter."}},"required":["url"]}},"language":{"type":"string","enum":["en","zh"],"description":"Language the text fields of this call are written in: 'en' or 'zh'. Write in the user's own language. Detected from the text when omitted."},"translations":{"type":"object","description":"The same text in the other language, keyed by language code: { \"zh\": { ... } } for a record written in English, { \"en\": { ... } } for one written in Chinese. ALWAYS provide it unless the user declines: GitDex shows each visitor one language. Translate every one of these fields that the original has: description, capabilities, pricing_notes. Lists keep the same number of items in the same order. Translate faithfully; add no claims and drop no limits. Never mix two languages inside one field.","properties":{"en":{"type":"object","properties":{"description":{"type":"string","maxLength":2000},"capabilities":{"type":"array","items":{"type":"string"},"description":"Same number of items as the original, in the same order."},"pricing_notes":{"type":"string","maxLength":500},"screenshots":{"type":"array","items":{"type":"string"},"maxItems":8,"description":"OPTIONAL. Public https URLs of screenshots that show the software in THIS language. Only when such screenshots exist; leave out otherwise and readers of this language see the record's own screenshots."}},"additionalProperties":false},"zh":{"type":"object","properties":{"description":{"type":"string","maxLength":2000},"capabilities":{"type":"array","items":{"type":"string"},"description":"Same number of items as the original, in the same order."},"pricing_notes":{"type":"string","maxLength":500},"screenshots":{"type":"array","items":{"type":"string"},"maxItems":8,"description":"OPTIONAL. Public https URLs of screenshots that show the software in THIS language. Only when such screenshots exist; leave out otherwise and readers of this language see the record's own screenshots."}},"additionalProperties":false}},"additionalProperties":false},"change_note":{"type":"string","description":"One sentence saying what changed and why. Shown publicly in the record's history.","maxLength":300},"confirmed":{"type":"boolean","description":"Set true ONLY after the user has seen the exact preview returned by a call without it and explicitly approved. Never set it on your own initiative."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_CANDIDATE / CONFLICT / INVALID_STATE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/users/{user_id}":{"get":{"operationId":"get_user","summary":"Get a public author profile","description":"Get the public profile of someone who published on GitDex: their display name and how many software records and requests they published. USE WHEN the user asks who submitted a record or what else that author published; then list the records with search_software (submitted_by) or search_requests (requested_by). NEEDS user_id, the `submitted_by.id`, `owner.id` or `proposed_by.id` of a record. NO side effects; public; no confirmation. Returns nothing private: no email or sign-in details. A display name proves no identity. Recovery: NOT_FOUND means the id is wrong; take it from a record.","tags":["users"],"security":[],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string"},"description":"User ID (UUID) from a record's submitted_by.id, owner.id or proposed_by.id."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/requests":{"get":{"operationId":"search_requests","summary":"Search requests","description":"Search public software requests. USE WHEN (a) a user is unsatisfied with existing software and you need to check for a similar request before creating one, or (b) a creator wants to discover demand to find or build software for. Optional keyword query, status and platform filters. NO side effects; public. Similar requests are suggestions: compare must_have constraints before treating two requests as the same need. A resolved request carries `resolved_by`, the software its requester accepted.","tags":["requests"],"security":[],"parameters":[{"name":"q","in":"query","required":false,"description":"Keywords describing the need.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"'active' = open + proposals_available.","schema":{"type":"string","enum":["active","all","open","proposals_available","resolved","closed"],"default":"active"}},{"name":"platform","in":"query","required":false,"description":"Only requests targeting this platform, e.g. 'ios'.","schema":{"type":"string"}},{"name":"requested_by","in":"query","required":false,"description":"Only requests published by this user: the `owner.id` of a request.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"'updated' = most recently changed first; with status 'resolved' that is the most recently resolved.","schema":{"type":"string","enum":["relevance","newest","updated","interest","proposals"],"default":"relevance"}},{"name":"limit","in":"query","required":false,"description":"Page size (max 50).","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","required":false,"description":"Items to skip; use next_offset from the previous page.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create_request","summary":"Publish a software request","description":"Publish a NEW public software request. USE ONLY WHEN the user explicitly asked to publish a request AND has seen the public preview. A search, a question, or dissatisfaction with results is NOT consent to publish. NEEDS title, goal and at least one must_have; add platforms and price_constraint when known. Write the fields in the user's language and add the other language (English or Chinese) in `translations`, so the request is published in both. Write only what the user wants public: no names, contact details, account data, private code or conversation excerpts. SIDE EFFECT: creates a public record visible to everyone. REQUIRES sign-in. FLOW: call first WITHOUT confirmed to get the exact preview, privacy warnings and similar existing requests; if a similar request fits, offer support_request instead; otherwise show the preview (both language versions), get explicit approval, then call again with confirmed=true and the same idempotency_key. Recovery: VALIDATION_FAILED lists the fields to fix.","tags":["requests"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200},"description":"Unique key for this intended write (e.g. a UUID). Reuse the SAME key when retrying the same write so it is applied once."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Short public title, e.g. 'Free iOS home inventory app'.","minLength":5,"maxLength":140},"goal":{"type":"string","description":"The task the user wants to accomplish.","minLength":10,"maxLength":2000},"must_have":{"type":"array","items":{"type":"string"},"description":"Conditions that must all be met for the request to be solved."},"nice_to_have":{"type":"array","items":{"type":"string"},"description":"Optional preferences."},"platforms":{"type":"array","items":{"type":"string"},"description":"Target platforms, e.g. ['ios']."},"price_constraint":{"type":"string","description":"Price limit in plain words, e.g. 'no recurring subscription'."},"other_constraints":{"type":"array","items":{"type":"string"},"description":"Other constraints such as offline use or privacy requirements."},"language":{"type":"string","enum":["en","zh"],"description":"Language the text fields of this call are written in: 'en' or 'zh'. Write in the user's own language. Detected from the text when omitted."},"translations":{"type":"object","description":"The same text in the other language, keyed by language code: { \"zh\": { ... } } for a record written in English, { \"en\": { ... } } for one written in Chinese. ALWAYS provide it unless the user declines: GitDex shows each visitor one language. Translate every one of these fields that the original has: title, goal, must_have, nice_to_have, price_constraint, other_constraints. Lists keep the same number of items in the same order. Translate faithfully; add no claims and drop no limits. Never mix two languages inside one field.","properties":{"en":{"type":"object","properties":{"title":{"type":"string","maxLength":140},"goal":{"type":"string","maxLength":2000},"must_have":{"type":"array","items":{"type":"string"},"description":"Same number of items as the original, in the same order."},"nice_to_have":{"type":"array","items":{"type":"string"},"description":"Same number of items as the original, in the same order."},"price_constraint":{"type":"string","maxLength":300},"other_constraints":{"type":"array","items":{"type":"string"},"description":"Same number of items as the original, in the same order."}},"additionalProperties":false},"zh":{"type":"object","properties":{"title":{"type":"string","maxLength":140},"goal":{"type":"string","maxLength":2000},"must_have":{"type":"array","items":{"type":"string"},"description":"Same number of items as the original, in the same order."},"nice_to_have":{"type":"array","items":{"type":"string"},"description":"Same number of items as the original, in the same order."},"price_constraint":{"type":"string","maxLength":300},"other_constraints":{"type":"array","items":{"type":"string"},"description":"Same number of items as the original, in the same order."}},"additionalProperties":false}},"additionalProperties":false},"confirmed":{"type":"boolean","description":"Set true ONLY after the user has seen the exact preview returned by a call without it and explicitly approved. Never set it on your own initiative."}},"required":["title","goal","must_have"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_CANDIDATE / CONFLICT / INVALID_STATE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/requests/{request_id}":{"get":{"operationId":"get_request","summary":"Get request details","description":"Get one request with its goal, must-have and nice-to-have constraints, interest count and all proposals. USE WHEN evaluating whether software satisfies a request, before proposing a solution, or before the requester records a verdict. NO side effects; public. interest_count is the requester plus supporters, not purchase intent. A proposal with status 'proposed' has not been accepted.","tags":["requests"],"security":[],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string"},"description":"Request ID (req_...)."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"update_request","summary":"Edit my request","description":"Change a request the signed-in user published: title, goal, must_have, nice_to_have, platforms, price_constraint or other_constraints. USE WHEN the requester asks to correct or sharpen their request. Possible ONLY while the request is open and nobody has proposed a solution yet; after that its conditions are what proposers answered to, so the user must close it (close_request) and publish a new one. SIDE EFFECT: publishes a new version and notifies supporters. REQUIRES sign-in as the requester. Send only the fields that change; everything else stays as it is. If any text field changes, the old translation no longer matches: send `translations` again for the other language or it is dropped. NOTHING IS ERASED: the version being replaced stays publicly visible in the record's history, so an edit cannot be used to hide what was published (to take down private or unlawful text, tell the user to report the record). FLOW: call WITHOUT confirmed to get the preview showing the new values next to the ones they replace, show it, get explicit approval, then call with confirmed=true and the same idempotency_key. Recovery: INVALID_STATE means it has proposals, is closed or resolved, or nothing would change; FORBIDDEN means it is someone else's request.","tags":["requests"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string"},"description":"Request ID (req_...)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200},"description":"Unique key for this intended write (e.g. a UUID). Reuse the SAME key when retrying the same write so it is applied once."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Short public title.","minLength":5,"maxLength":140},"goal":{"type":"string","description":"The task the user wants to accomplish.","minLength":10,"maxLength":2000},"must_have":{"type":"array","items":{"type":"string"},"description":"Conditions that must all be met. Replaces the whole list."},"nice_to_have":{"type":"array","items":{"type":"string"},"description":"Optional preferences. Replaces the whole list."},"platforms":{"type":"array","items":{"type":"string"},"description":"Target platforms. Replaces the whole list."},"price_constraint":{"type":["string","null"],"description":"Price limit in plain words; null removes it."},"other_constraints":{"type":"array","items":{"type":"string"},"description":"Other constraints. Replaces the whole list."},"language":{"type":"string","enum":["en","zh"],"description":"Language the text fields of this call are written in: 'en' or 'zh'. Write in the user's own language. Detected from the text when omitted."},"translations":{"type":"object","description":"The same text in the other language, keyed by language code: { \"zh\": { ... } } for a record written in English, { \"en\": { ... } } for one written in Chinese. ALWAYS provide it unless the user declines: GitDex shows each visitor one language. Translate every one of these fields that the original has: title, goal, must_have, nice_to_have, price_constraint, other_constraints. Lists keep the same number of items in the same order. Translate faithfully; add no claims and drop no limits. Never mix two languages inside one field.","properties":{"en":{"type":"object","properties":{"title":{"type":"string","maxLength":140},"goal":{"type":"string","maxLength":2000},"must_have":{"type":"array","items":{"type":"string"},"description":"Same number of items as the original, in the same order."},"nice_to_have":{"type":"array","items":{"type":"string"},"description":"Same number of items as the original, in the same order."},"price_constraint":{"type":"string","maxLength":300},"other_constraints":{"type":"array","items":{"type":"string"},"description":"Same number of items as the original, in the same order."}},"additionalProperties":false},"zh":{"type":"object","properties":{"title":{"type":"string","maxLength":140},"goal":{"type":"string","maxLength":2000},"must_have":{"type":"array","items":{"type":"string"},"description":"Same number of items as the original, in the same order."},"nice_to_have":{"type":"array","items":{"type":"string"},"description":"Same number of items as the original, in the same order."},"price_constraint":{"type":"string","maxLength":300},"other_constraints":{"type":"array","items":{"type":"string"},"description":"Same number of items as the original, in the same order."}},"additionalProperties":false}},"additionalProperties":false},"change_note":{"type":"string","description":"One sentence saying what changed and why. Shown publicly in the record's history.","maxLength":300},"confirmed":{"type":"boolean","description":"Set true ONLY after the user has seen the exact preview returned by a call without it and explicitly approved. Never set it on your own initiative."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_CANDIDATE / CONFLICT / INVALID_STATE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/requests/{request_id}/support":{"post":{"operationId":"support_request","summary":"Support an existing request","description":"Add the user as a supporter (follower) of an existing request. USE WHEN the user agrees that an existing request matches their need, instead of publishing a duplicate. NEEDS request_id. SIDE EFFECT: increments the public interest count by at most one per user and subscribes the user to updates (set notifications_enabled=false to follow silently). REQUIRES sign-in and the user's agreement to support this specific request. Recovery: INVALID_STATE means the request is resolved/closed or the user owns it.","tags":["requests"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string"},"description":"Request ID (req_...)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200},"description":"Unique key for this intended write (e.g. a UUID). Reuse the SAME key when retrying the same write so it is applied once."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"notifications_enabled":{"type":"boolean","default":true,"description":"Receive updates about this request."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_CANDIDATE / CONFLICT / INVALID_STATE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"unsupport_request","summary":"Stop supporting a request","description":"Remove the signed-in user's support and subscription for a request.","tags":["requests"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string"},"description":"Request ID (req_...)."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_CANDIDATE / CONFLICT / INVALID_STATE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/solutions":{"post":{"operationId":"propose_solution","summary":"Propose software as a solution to a request","description":"Link a software record to a request as a candidate solution. USE WHEN a creator believes listed software satisfies a request, whether they found it or built it. NEEDS request_id, software_id (submit the software first if it has no record), coverage_notes explaining which must-haves are covered, and unmet_requirements listing every known gap honestly. Write them in the user's language and add the other language (English or Chinese) in `translations`; the translation must list the same gaps. SIDE EFFECT: creates a public proposal with status 'proposed' and notifies the requester and supporters. It does NOT resolve the request and you must not tell the user it did. REQUIRES sign-in. FLOW: call WITHOUT confirmed to get the preview, show it, get explicit approval, then call with confirmed=true and the same idempotency_key. Recovery: DUPLICATE_CANDIDATE means this software is already proposed for this request; INVALID_STATE means the request no longer accepts proposals.","tags":["solutions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200},"description":"Unique key for this intended write (e.g. a UUID). Reuse the SAME key when retrying the same write so it is applied once."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","description":"Request ID (req_...)."},"software_id":{"type":"string","description":"Software ID (sw_...) or slug."},"coverage_notes":{"type":"string","description":"How the software covers the request's must-haves.","minLength":10,"maxLength":2000},"unmet_requirements":{"type":"array","items":{"type":"string"},"description":"Requirements that are not met or not verified."},"language":{"type":"string","enum":["en","zh"],"description":"Language the text fields of this call are written in: 'en' or 'zh'. Write in the user's own language. Detected from the text when omitted."},"translations":{"type":"object","description":"The same text in the other language, keyed by language code: { \"zh\": { ... } } for a record written in English, { \"en\": { ... } } for one written in Chinese. ALWAYS provide it unless the user declines: GitDex shows each visitor one language. Translate every one of these fields that the original has: coverage_notes, unmet_requirements. Lists keep the same number of items in the same order. Translate faithfully; add no claims and drop no limits. Never mix two languages inside one field.","properties":{"en":{"type":"object","properties":{"coverage_notes":{"type":"string","maxLength":2000},"unmet_requirements":{"type":"array","items":{"type":"string"},"description":"Same number of items as the original, in the same order."}},"additionalProperties":false},"zh":{"type":"object","properties":{"coverage_notes":{"type":"string","maxLength":2000},"unmet_requirements":{"type":"array","items":{"type":"string"},"description":"Same number of items as the original, in the same order."}},"additionalProperties":false}},"additionalProperties":false},"evidence":{"type":"array","description":"Sources supporting the coverage claims.","items":{"type":"object","properties":{"url":{"type":"string","description":"Public http(s) URL of the source."},"claim":{"type":"string","description":"What this source supports, in one sentence."},"source_type":{"type":"string","enum":["official_site","repository","documentation","store_listing","review","other"]},"verification_level":{"type":"string","enum":["claimed","documented","unknown"],"description":"claimed = the vendor says so; documented = stated in official docs/repo you actually read; unknown = not checked. 'tested' cannot be asserted by a submitter."}},"required":["url"]}},"confirmed":{"type":"boolean","description":"Set true ONLY after the user has seen the exact preview returned by a call without it and explicitly approved. Never set it on your own initiative."}},"required":["request_id","software_id","coverage_notes"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_CANDIDATE / CONFLICT / INVALID_STATE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/solutions/{proposal_id}/confirm":{"post":{"operationId":"confirm_solution","summary":"Record a verdict on a proposed solution","description":"Record whether a proposed solution meets the user's needs. USE ONLY WHEN the signed-in user is the original requester (or a supporter) of the request AND has told you their verdict in their own words after looking at or trying the software. verdict: 'accepted' = meets ALL must-haves, 'partial' = partly, 'rejected' = does not. Never infer acceptance from a click, from silence, or from the creator's claims. SIDE EFFECT: public feedback. Only the original requester's 'accepted' marks the request resolved; 'partial' and 'rejected' keep it open; a supporter's verdict is recorded as individual feedback and changes no status. A proposer cannot record a verdict on their own proposal. REQUIRES sign-in. FLOW: call WITHOUT confirmed to get the preview and effect, confirm with the user, then call with confirmed=true and the same idempotency_key. Recovery: FORBIDDEN means this user may not judge this proposal; do not retry.","tags":["solutions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"proposal_id","in":"path","required":true,"schema":{"type":"string"},"description":"Proposal ID (sol_...)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200},"description":"Unique key for this intended write (e.g. a UUID). Reuse the SAME key when retrying the same write so it is applied once."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","description":"Request ID the proposal belongs to; checked for consistency when given."},"verdict":{"type":"string","enum":["accepted","partial","rejected"]},"feedback":{"type":"string","description":"Optional public feedback explaining the verdict.","maxLength":2000},"confirmed":{"type":"boolean","description":"Set true ONLY after the user has seen the exact preview returned by a call without it and explicitly approved. Never set it on your own initiative."}},"required":["verdict"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_CANDIDATE / CONFLICT / INVALID_STATE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/activity":{"get":{"operationId":"get_my_activity","summary":"Get my GitDex activity","description":"List the signed-in user's own requests, submitted software, proposals and followed requests. USE WHEN the user asks about their GitDex activity or you need their request/proposal IDs (e.g. to find proposals awaiting their verdict). NO side effects. REQUIRES sign-in; returns only the caller's own data.","tags":["me"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["all","requests","software","proposals","subscriptions"],"default":"all"}},{"name":"limit","in":"query","required":false,"description":"Page size (max 50).","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","required":false,"description":"Items to skip; use next_offset from the previous page.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/solutions/{proposal_id}":{"get":{"operationId":"get_solution","summary":"Get solution proposal details","description":"Get one solution proposal with its request, software, and all recorded verdicts. USE WHEN showing a proposal to the requester before confirm_solution, or checking a proposal's acceptance status. NO side effects; public. Only feedback with is_owner=true is from the original requester.","tags":["solutions"],"security":[],"parameters":[{"name":"proposal_id","in":"path","required":true,"schema":{"type":"string"},"description":"Proposal ID (sol_...)."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"update_solution","summary":"Edit my proposal","description":"Change the coverage_notes, unmet_requirements or evidence of a proposal the signed-in user made. USE WHEN the proposer asks to correct their proposal. Possible ONLY while it is 'proposed' and nobody has recorded a verdict on it; afterwards the verdict refers to that text, so the user must withdraw it (withdraw_proposal) and propose again. SIDE EFFECT: publishes a new version and notifies the requester. It never resolves the request. REQUIRES sign-in as the proposer. Send only the fields that change; everything else stays as it is. If any text field changes, the old translation no longer matches: send `translations` again for the other language or it is dropped. NOTHING IS ERASED: the version being replaced stays publicly visible in the record's history, so an edit cannot be used to hide what was published (to take down private or unlawful text, tell the user to report the record). FLOW: call WITHOUT confirmed to get the preview showing the new values next to the ones they replace, show it, get explicit approval, then call with confirmed=true and the same idempotency_key. Recovery: INVALID_STATE means a verdict exists, the proposal is no longer 'proposed', or nothing would change; FORBIDDEN means it is someone else's proposal.","tags":["solutions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"proposal_id","in":"path","required":true,"schema":{"type":"string"},"description":"Proposal ID (sol_...)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200},"description":"Unique key for this intended write (e.g. a UUID). Reuse the SAME key when retrying the same write so it is applied once."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"coverage_notes":{"type":"string","description":"How the software covers the request's must-haves.","minLength":10,"maxLength":2000},"unmet_requirements":{"type":"array","items":{"type":"string"},"description":"Requirements that are not met or not verified. Replaces the whole list."},"evidence":{"type":"array","description":"Sources supporting the coverage claims. Replaces the evidence this user gave before; [] removes it.","items":{"type":"object","properties":{"url":{"type":"string","description":"Public http(s) URL of the source."},"claim":{"type":"string","description":"What this source supports, in one sentence."},"source_type":{"type":"string","enum":["official_site","repository","documentation","store_listing","review","other"]},"verification_level":{"type":"string","enum":["claimed","documented","unknown"],"description":"claimed = the vendor says so; documented = stated in official docs/repo you actually read; unknown = not checked. 'tested' cannot be asserted by a submitter."}},"required":["url"]}},"language":{"type":"string","enum":["en","zh"],"description":"Language the text fields of this call are written in: 'en' or 'zh'. Write in the user's own language. Detected from the text when omitted."},"translations":{"type":"object","description":"The same text in the other language, keyed by language code: { \"zh\": { ... } } for a record written in English, { \"en\": { ... } } for one written in Chinese. ALWAYS provide it unless the user declines: GitDex shows each visitor one language. Translate every one of these fields that the original has: coverage_notes, unmet_requirements. Lists keep the same number of items in the same order. Translate faithfully; add no claims and drop no limits. Never mix two languages inside one field.","properties":{"en":{"type":"object","properties":{"coverage_notes":{"type":"string","maxLength":2000},"unmet_requirements":{"type":"array","items":{"type":"string"},"description":"Same number of items as the original, in the same order."}},"additionalProperties":false},"zh":{"type":"object","properties":{"coverage_notes":{"type":"string","maxLength":2000},"unmet_requirements":{"type":"array","items":{"type":"string"},"description":"Same number of items as the original, in the same order."}},"additionalProperties":false}},"additionalProperties":false},"change_note":{"type":"string","description":"One sentence saying what changed and why. Shown publicly in the record's history.","maxLength":300},"confirmed":{"type":"boolean","description":"Set true ONLY after the user has seen the exact preview returned by a call without it and explicitly approved. Never set it on your own initiative."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_CANDIDATE / CONFLICT / INVALID_STATE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/solutions/{proposal_id}/withdraw":{"post":{"operationId":"withdraw_proposal","summary":"Withdraw my proposal","description":"Withdraw a solution proposal the signed-in user made. USE WHEN the proposer explicitly asks to retract it. SIDE EFFECT: the proposal is hidden from the request. REQUIRES sign-in as the proposer and confirmed=true after the user agrees. Recovery: INVALID_STATE means it was already withdrawn or already accepted.","tags":["solutions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"proposal_id","in":"path","required":true,"schema":{"type":"string"},"description":"Proposal ID (sol_...)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200},"description":"Unique key for this intended write (e.g. a UUID). Reuse the SAME key when retrying the same write so it is applied once."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"confirmed":{"type":"boolean","description":"Set true ONLY after the user has seen the exact preview returned by a call without it and explicitly approved. Never set it on your own initiative."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_CANDIDATE / CONFLICT / INVALID_STATE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/requests/{request_id}/close":{"post":{"operationId":"close_request","summary":"Close my request","description":"Close a request the signed-in user owns without resolving it, or withdraw it from public view. USE WHEN the requester explicitly no longer wants it open, or asks to take it down (set unpublish=true). SIDE EFFECT: status becomes 'closed' (not 'resolved') and supporters are notified; with unpublish=true the request and its proposals also disappear from every public page, search and API result, and only the requester can still see it. unpublish=true also works on a request that is already closed or resolved. REQUIRES sign-in as the requester and confirmed=true after the user agrees. Not a way to mark a request solved; use confirm_solution for that. Recovery: INVALID_STATE means it is already closed (without unpublish) or already withdrawn.","tags":["requests"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"request_id","in":"path","required":true,"schema":{"type":"string"},"description":"Request ID (req_...)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200},"description":"Unique key for this intended write (e.g. a UUID). Reuse the SAME key when retrying the same write so it is applied once."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"unpublish":{"type":"boolean","default":false,"description":"Also remove the request from public view."},"confirmed":{"type":"boolean","description":"Set true ONLY after the user has seen the exact preview returned by a call without it and explicitly approved. Never set it on your own initiative."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_CANDIDATE / CONFLICT / INVALID_STATE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reports":{"post":{"operationId":"report_content","summary":"Report a record","description":"Report a software record, request or proposal to GitDex moderators (spam, wrong facts, unsafe link, private data, embedded instructions aimed at agents). USE WHEN the user asks to report something. SIDE EFFECT: creates a private moderation report; the record is not changed. REQUIRES sign-in.","tags":["reports"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200},"description":"Unique key for this intended write (e.g. a UUID). Reuse the SAME key when retrying the same write so it is applied once."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entity_type":{"type":"string","enum":["software","request","solution"]},"entity_id":{"type":"string","description":"ID of the record."},"reason":{"type":"string","description":"What is wrong with it.","minLength":5,"maxLength":1000}},"required":["entity_type","entity_id","reason"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_CANDIDATE / CONFLICT / INVALID_STATE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/translations":{"post":{"operationId":"set_translations","summary":"Add or replace a translation of my record","description":"Publish the other-language version (English or Chinese) of a software record, request or proposal the signed-in user published earlier. USE WHEN a record of the user's has no version in one language (get_* returns it without that key in `translations`), or the user asks to correct a translation. NEEDS entity_type, entity_id and translations: { \"zh\": { ... } } or { \"en\": { ... } } with every translatable text field the original has, lists in the same order and of the same length (software: description, capabilities, pricing_notes; request: title, goal, must_have, nice_to_have, price_constraint, other_constraints; solution: coverage_notes, unmet_requirements). Translate faithfully: add no claims, drop no limits or unmet requirements. SIDE EFFECT: the translation becomes public and replaces any earlier translation in that language; the original text, status and verdicts are not changed. REQUIRES sign-in as the user who published the record. FLOW: call WITHOUT confirmed to get the preview with the original next to the translation, show both, get explicit approval, then call with confirmed=true and the same idempotency_key. Recovery: FORBIDDEN means the record belongs to someone else, do not retry; VALIDATION_FAILED lists the fields that do not mirror the original.","tags":["translations"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200},"description":"Unique key for this intended write (e.g. a UUID). Reuse the SAME key when retrying the same write so it is applied once."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entity_type":{"type":"string","enum":["software","request","solution"]},"entity_id":{"type":"string","description":"ID of the record: sw_... (or slug), req_... or sol_...."},"translations":{"type":"object","description":"Language versions keyed by language code. The key must not be the language the record itself is written in.","properties":{"en":{"type":"object","description":"The translatable fields of this record type, translated."},"zh":{"type":"object","description":"The translatable fields of this record type, translated."}},"additionalProperties":false},"confirmed":{"type":"boolean","description":"Set true ONLY after the user has seen the exact preview returned by a call without it and explicitly approved. Never set it on your own initiative."}},"required":["entity_type","entity_id","translations"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_CANDIDATE / CONFLICT / INVALID_STATE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/history":{"get":{"operationId":"get_history","summary":"Get earlier versions of a record","description":"List what a software record, request or proposal said before each edit. USE WHEN a record's `version` is above 1 and the user asks what changed, or you need the text a verdict, proposal or earlier answer was based on. NEEDS entity_type and entity_id. NO side effects; public. Returns current_version and earlier_versions (newest first) with their content, when each was published and replaced, and the author's change note. Only the current record is in force. Recovery: NOT_FOUND means the record does not exist or is no longer public.","tags":["history"],"security":[],"parameters":[{"name":"entity_type","in":"query","required":true,"schema":{"type":"string","enum":["software","request","solution"]}},{"name":"entity_id","in":"query","required":true,"description":"ID of the record: sw_... (or slug), req_... or sol_....","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me":{"get":{"operationId":"get_me","summary":"Get my account","description":"The signed-in user's profile and notification preferences.","tags":["me"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"update_me","summary":"Update my account","description":"Change the public display name or notification preferences.","tags":["me"],"security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"display_name":{"type":"string","description":"Public display name.","minLength":2,"maxLength":60},"notification_preferences":{"type":"object","properties":{"in_app":{"type":"boolean"},"email":{"type":"boolean"}},"description":"Notification channels. Turning both off stops all notifications."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_CANDIDATE / CONFLICT / INVALID_STATE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/notifications":{"get":{"operationId":"list_notifications","summary":"List my notifications","description":"In-app notifications for the signed-in user, newest first.","tags":["me"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (max 50).","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","required":false,"description":"Items to skip; use next_offset from the previous page.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/notifications/read":{"post":{"operationId":"mark_notifications_read","summary":"Mark my notifications read","description":"Mark all of the signed-in user's notifications as read.","tags":["me"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_CANDIDATE / CONFLICT / INVALID_STATE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/tokens":{"get":{"operationId":"list_tokens","summary":"List my API tokens","description":"Active personal API tokens (prefix only). Browser session required.","tags":["me"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create_token","summary":"Create an API token","description":"Create a personal API token for agents and scripts. The token is shown once. Browser session required.","tags":["me"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Label for the token, e.g. 'Claude Code'.","maxLength":60}},"required":["name"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_CANDIDATE / CONFLICT / INVALID_STATE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/tokens/{token_id}":{"delete":{"operationId":"revoke_token","summary":"Revoke an API token","description":"Revoke one of the signed-in user's API tokens. Browser session required.","tags":["me"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"token_id","in":"path","required":true,"schema":{"type":"string"},"description":"Token ID (tok_...)."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_CANDIDATE / CONFLICT / INVALID_STATE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stats":{"get":{"operationId":"get_stats","summary":"Public network stats","description":"Counts of listed software, open requests, proposals, and requester-verified resolved requests.","tags":["stats"],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/admin/reports":{"get":{"operationId":"admin_list_reports","summary":"List reports (moderators)","description":"Reports users filed about records, newest first, each with the reported record, its state and its author. Moderators only, from a browser session.","tags":["admin"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","actioned","dismissed","all"],"default":"open"}},{"name":"limit","in":"query","required":false,"description":"Page size (max 50).","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","required":false,"description":"Items to skip; use next_offset from the previous page.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/admin/software":{"get":{"operationId":"admin_list_software","summary":"List software for review (moderators)","description":"Software listings by review status, newest first, including flagged and removed ones, with the submitter and the number of open reports. Moderators only, from a browser session.","tags":["admin"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"review_status","in":"query","required":false,"schema":{"type":"string","enum":["unreviewed","reviewed","flagged","removed","all"],"default":"unreviewed"}},{"name":"limit","in":"query","required":false,"description":"Page size (max 50).","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"offset","in":"query","required":false,"description":"Items to skip; use next_offset from the previous page.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/admin/moderate":{"post":{"operationId":"admin_moderate","summary":"Moderate a record (moderators)","description":"Change the moderation state of a record. Software: mark_reviewed (a moderator looked and found no violation; not a verification of its claims), flag (adds a public warning), remove, restore, clear_images. Request: remove, restore. Solution: remove (also un-resolves the request if it was the accepted one). SIDE EFFECTS: settles the open reports about the record, notifies its author, is audited. Moderators only, from a browser session; requires confirmed=true after a preview.","tags":["admin"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200},"description":"Unique key for this intended write (e.g. a UUID). Reuse the SAME key when retrying the same write so it is applied once."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entity_type":{"type":"string","enum":["software","request","solution"]},"entity_id":{"type":"string","description":"ID of the record."},"action":{"type":"string","enum":["mark_reviewed","flag","remove","restore","clear_images","clear_history"]},"note":{"type":"string","description":"Optional note sent to the record's author with the notification.","maxLength":300},"confirmed":{"type":"boolean","description":"Set true ONLY after the user has seen the exact preview returned by a call without it and explicitly approved. Never set it on your own initiative."}},"required":["entity_type","entity_id","action"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_CANDIDATE / CONFLICT / INVALID_STATE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/admin/reports/resolve":{"post":{"operationId":"admin_resolve_reports","summary":"Settle reports about a record (moderators)","description":"Mark every open report about one record as dismissed or actioned without changing the record. Moderators only, from a browser session.","tags":["admin"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200},"description":"Unique key for this intended write (e.g. a UUID). Reuse the SAME key when retrying the same write so it is applied once."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entity_type":{"type":"string","enum":["software","request","solution"]},"entity_id":{"type":"string","description":"ID of the reported record."},"resolution":{"type":"string","enum":["dismissed","actioned"]}},"required":["entity_type","entity_id","resolution"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_CANDIDATE / CONFLICT / INVALID_STATE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/admin/users/{user_id}/status":{"post":{"operationId":"admin_set_user_status","summary":"Suspend or reinstate an account (moderators)","description":"Suspend an account (it can no longer sign in, write or use API tokens; its records stay until removed) or make it active again. A moderator cannot change their own account. Moderators only, from a browser session; requires confirmed=true after a preview.","tags":["admin"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string"},"description":"User ID (UUID)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200},"description":"Unique key for this intended write (e.g. a UUID). Reuse the SAME key when retrying the same write so it is applied once."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","suspended"]},"confirmed":{"type":"boolean","description":"Set true ONLY after the user has seen the exact preview returned by a call without it and explicitly approved. Never set it on your own initiative."}},"required":["status"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"AUTH_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"FORBIDDEN","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"DUPLICATE_CANDIDATE / CONFLICT / INVALID_STATE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"VALIDATION_FAILED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"description":"CONFIRMATION_REQUIRED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"RATE_LIMITED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A GitDex personal API token (gdx_...) from /account, or an OAuth access token."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","recovery"],"properties":{"code":{"type":"string","enum":["AUTH_REQUIRED","CONFIRMATION_REQUIRED","DUPLICATE_CANDIDATE","VALIDATION_FAILED","RATE_LIMITED","FORBIDDEN","NOT_FOUND","CONFLICT","INVALID_STATE","INTERNAL"]},"message":{"type":"string"},"recovery":{"type":"string","description":"What a client or agent should do next."},"details":{"type":"object","description":"Code-specific data, e.g. preview, candidates, fields."}}}}}}}}