{"openapi":"3.1.0","info":{"title":"SaaSCity Maker API","version":"v1","description":"Read and edit your own SaaSCity listings, read their upvotes, search the directory and start listing drafts. Create a key at https://saascity.io/dashboard/settings/api. A draft is listed only after you open its claim URL, pick a plan and pay; every listing is reviewed by a person."},"servers":[{"url":"https://saascity.io/api/maker/v1"}],"security":[{"bearer":[]},{"apiKey":[]}],"paths":{"/me":{"get":{"operationId":"getMe","summary":"The account the key belongs to","description":"Use it to test a key.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string"},"profile_url":{"type":"string"},"listings":{"type":"integer"}}}}}},"401":{"description":"Missing, malformed, unknown or revoked key (INVALID_KEY).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"DAILY_LIMIT_REACHED on POST /drafts, or over 60 requests a minute for this key (RATE_LIMITED). See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure (SERVER_ERROR). Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/listings":{"get":{"operationId":"listMyListings","summary":"Your listings, newest first","parameters":[{"name":"state","in":"query","schema":{"type":"string","enum":["awaiting_payment","in_review","scheduled","live","rejected","archived"],"description":"awaiting_payment: plan not paid yet. in_review: queued for a person. scheduled: approved, launch week not started. live: on the site."}},{"name":"live_after","in":"query","description":"Only listings that went live at or after this time (live_at). Inclusive. ISO 8601 (2026-11-19T08:00:00Z or 2026-11-19), or Unix time in seconds or milliseconds.","schema":{"type":"string","format":"date-time"}},{"name":"live_before","in":"query","description":"Only listings that went live at or before this time (live_at). Inclusive. ISO 8601 (2026-11-19T08:00:00Z or 2026-11-19), or Unix time in seconds or milliseconds.","schema":{"type":"string","format":"date-time"}},{"name":"created_after","in":"query","description":"Only items created at or after this time. Inclusive. ISO 8601 (2026-11-19T08:00:00Z or 2026-11-19), or Unix time in seconds or milliseconds.","schema":{"type":"string","format":"date-time"}},{"name":"created_before","in":"query","description":"Only items created at or before this time. Inclusive. ISO 8601 (2026-11-19T08:00:00Z or 2026-11-19), or Unix time in seconds or milliseconds.","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","description":"Items to skip. Send the next_offset of the previous page.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"listings":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"has_more":{"type":"boolean","description":"True when another page follows."},"next_offset":{"type":["integer","null"],"description":"offset of the next page, null on the last page."}}}}}},"400":{"description":"Unknown state or bad date (VALIDATION_FAILED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked key (INVALID_KEY).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"DAILY_LIMIT_REACHED on POST /drafts, or over 60 requests a minute for this key (RATE_LIMITED). See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure (SERVER_ERROR). Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/listings/{id}":{"get":{"operationId":"getMyListing","summary":"One of your listings, by id or slug","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Listing"}}}},"401":{"description":"Missing, malformed, unknown or revoked key (INVALID_KEY).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not one of your listings (NOT_FOUND).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"DAILY_LIMIT_REACHED on POST /drafts, or over 60 requests a minute for this key (RATE_LIMITED). See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure (SERVER_ERROR). Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateMyListing","summary":"Edit one of your listings","description":"Send only the fields to change; null clears twitter_url, github_url or pricing_model. Same rules as the edit form on saascity.io: the edit sends the listing back to review (state in_review) until a person approves it, and a rejected listing cannot be edited. A new website_url gets the same free-host and one-listing-per-domain checks as a new listing.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"additionalProperties":false,"properties":{"title":{"type":"string","minLength":3,"maxLength":60},"tagline":{"type":"string","minLength":10,"maxLength":100},"description":{"type":"string","minLength":50,"maxLength":5000},"category":{"type":"string","enum":["ai","saas","productivity","devtools","design","marketing","fintech","health","mobile","games","web3","molt","directories","other"]},"molt_subcategory":{"type":["string","null"],"enum":["social_forum","aggregator_reader","token_launchpad_crypto","developer_tools_integration","gaming_competition","visualization_world","marketplace_economy","messaging_private_comm",null],"description":"Required when category is molt, refused otherwise."},"website_url":{"type":"string","maxLength":500},"twitter_url":{"type":["string","null"],"maxLength":500},"github_url":{"type":["string","null"],"maxLength":500},"tags":{"type":"array","items":{"type":"string","maxLength":30},"maxItems":10},"pricing_model":{"type":["string","null"],"enum":["free","freemium","paid","free_trial",null]}}}}}},"responses":{"200":{"description":"Saved. The listing is back in review.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Listing"}}}},"400":{"description":"Invalid fields (VALIDATION_FAILED), with details, or BANNED_CONTENT.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked key (INVALID_KEY).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not one of your listings (NOT_FOUND).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Rejected listing (NOT_EDITABLE), or the domain already has another listing (DUPLICATE_DOMAIN).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body over 32KB (PAYLOAD_TOO_LARGE).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Free subdomain host (FREE_HOSTING_DOMAIN).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"DAILY_LIMIT_REACHED on POST /drafts, or over 60 requests a minute for this key (RATE_LIMITED). See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure (SERVER_ERROR). Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/upvotes":{"get":{"operationId":"listMyUpvotes","summary":"Upvotes on your listings, newest first","description":"Voting is anonymous: an upvote says when and on which listing, never who. id is opaque and stable, for deduplication only. Your own votes are left out.","parameters":[{"name":"created_after","in":"query","description":"Only items created at or after this time. Inclusive. ISO 8601 (2026-11-19T08:00:00Z or 2026-11-19), or Unix time in seconds or milliseconds.","schema":{"type":"string","format":"date-time"}},{"name":"created_before","in":"query","description":"Only items created at or before this time. Inclusive. ISO 8601 (2026-11-19T08:00:00Z or 2026-11-19), or Unix time in seconds or milliseconds.","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","description":"Items to skip. Send the next_offset of the previous page.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"upvotes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"listing_id":{"type":"string"},"listing_slug":{"type":"string"},"listing_title":{"type":"string"},"listing_url":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}},"has_more":{"type":"boolean","description":"True when another page follows."},"next_offset":{"type":["integer","null"],"description":"offset of the next page, null on the last page."}}}}}},"400":{"description":"Bad date (VALIDATION_FAILED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked key (INVALID_KEY).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"DAILY_LIMIT_REACHED on POST /drafts, or over 60 requests a minute for this key (RATE_LIMITED). See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure (SERVER_ERROR). Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/search":{"get":{"operationId":"searchListings","summary":"Search live listings in the directory","parameters":[{"name":"query","in":"query","schema":{"type":"string","maxLength":100},"description":"Matched against title and tagline"},{"name":"category","in":"query","schema":{"type":"string","enum":["ai","saas","productivity","devtools","design","marketing","fintech","health","mobile","games","web3","molt","directories","other"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["newest","points"],"default":"newest"}},{"name":"live_after","in":"query","description":"Only listings that went live at or after this time (live_at). Inclusive. ISO 8601 (2026-11-19T08:00:00Z or 2026-11-19), or Unix time in seconds or milliseconds.","schema":{"type":"string","format":"date-time"}},{"name":"live_before","in":"query","description":"Only listings that went live at or before this time (live_at). Inclusive. ISO 8601 (2026-11-19T08:00:00Z or 2026-11-19), or Unix time in seconds or milliseconds.","schema":{"type":"string","format":"date-time"}},{"name":"created_after","in":"query","description":"Only items created at or after this time. Inclusive. ISO 8601 (2026-11-19T08:00:00Z or 2026-11-19), or Unix time in seconds or milliseconds.","schema":{"type":"string","format":"date-time"}},{"name":"created_before","in":"query","description":"Only items created at or before this time. Inclusive. ISO 8601 (2026-11-19T08:00:00Z or 2026-11-19), or Unix time in seconds or milliseconds.","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","description":"Page size.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","description":"Items to skip. Send the next_offset of the previous page.","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"listings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"tagline":{"type":"string"},"category":{"type":"string"},"website_url":{"type":["string","null"]},"points":{"type":"integer"},"url":{"type":"string"},"live_at":{"type":["string","null"],"format":"date-time","description":"When the listing showed on the site: the later of its approval and the start of its launch week. Null until approved; in the future while scheduled."},"created_at":{"type":"string","format":"date-time"}}}},"has_more":{"type":"boolean","description":"True when another page follows."},"next_offset":{"type":["integer","null"],"description":"offset of the next page, null on the last page."}}}}}},"400":{"description":"Bad sort, category or date (VALIDATION_FAILED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked key (INVALID_KEY).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"DAILY_LIMIT_REACHED on POST /drafts, or over 60 requests a minute for this key (RATE_LIMITED). See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure (SERVER_ERROR). Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/drafts":{"post":{"operationId":"createDraft","summary":"Start a listing draft","description":"Returns a claim URL. Nothing is listed, booked or charged until a person opens it, signs in, picks a plan, pays and submits the form. Up to 10 drafts a day per account. Drafts expire after 7 days.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","tagline","category","description","website_url"],"properties":{"title":{"type":"string","minLength":3,"maxLength":60},"tagline":{"type":"string","minLength":10,"maxLength":100},"category":{"type":"string","enum":["ai","saas","productivity","devtools","design","marketing","fintech","health","mobile","games","web3","molt","directories","other"]},"description":{"type":"string","minLength":50,"maxLength":5000},"website_url":{"type":"string","format":"uri","maxLength":500,"description":"https, on its own domain (free subdomain hosts are refused)"},"twitter_url":{"type":"string","maxLength":200},"github_url":{"type":"string","maxLength":200},"tags":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":10}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"claim_url":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"next_step":{"type":"string"}}}}}},"400":{"description":"Invalid fields (VALIDATION_FAILED), with details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, unknown or revoked key (INVALID_KEY).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The domain already has a listing (DUPLICATE_DOMAIN).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body over 32KB (PAYLOAD_TOO_LARGE).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Free subdomain host (FREE_HOSTING_DOMAIN).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"DAILY_LIMIT_REACHED on POST /drafts, or over 60 requests a minute for this key (RATE_LIMITED). See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporary failure (SERVER_ERROR). Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Authorization: Bearer scm_live_..."},"apiKey":{"type":"apiKey","in":"header","name":"X-Api-Key"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_KEY","VALIDATION_FAILED","DUPLICATE_DOMAIN","FREE_HOSTING_DOMAIN","DAILY_LIMIT_REACHED","NOT_FOUND","NOT_EDITABLE","BANNED_CONTENT","PAYLOAD_TOO_LARGE","RATE_LIMITED","SERVER_ERROR"]},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}},"Listing":{"type":"object","required":["id","slug","title","state","url"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"title":{"type":"string"},"tagline":{"type":"string"},"description":{"type":"string"},"category":{"type":"string","enum":["ai","saas","productivity","devtools","design","marketing","fintech","health","mobile","games","web3","molt","directories","other"]},"molt_subcategory":{"type":["string","null"],"enum":["social_forum","aggregator_reader","token_launchpad_crypto","developer_tools_integration","gaming_competition","visualization_world","marketplace_economy","messaging_private_comm",null],"description":"Set only when category is molt."},"tags":{"type":"array","items":{"type":"string"}},"pricing_model":{"type":["string","null"],"enum":["free","freemium","paid","free_trial",null]},"website_url":{"type":["string","null"]},"twitter_url":{"type":["string","null"]},"github_url":{"type":["string","null"]},"logo_url":{"type":["string","null"]},"state":{"type":"string","enum":["awaiting_payment","in_review","scheduled","live","rejected","archived"],"description":"awaiting_payment: plan not paid yet. in_review: queued for a person. scheduled: approved, launch week not started. live: on the site."},"status":{"type":"string","enum":["pending","active","rejected","archived"],"description":"Raw review status."},"backlink_type":{"type":"string","enum":["dofollow","nofollow"]},"launch_week":{"type":["string","null"],"format":"date","description":"Monday (UTC) of the launch week."},"points":{"type":"integer"},"upvotes":{"type":"integer"},"url":{"type":"string","description":"Public listing page. Answers 404 until the listing is live."},"live_at":{"type":["string","null"],"format":"date-time","description":"When the listing showed on the site: the later of its approval and the start of its launch week. Null until approved; in the future while scheduled."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}