{"openapi":"3.1.0","info":{"title":"Directoryz API","version":"1.0.0","summary":"Programmatically manage Directoryz directories and listings.","description":"The Directoryz API is a workspace-scoped REST API. Create an API key in the Directoryz dashboard, send it as a Bearer token, and grant only the permissions your integration needs. API keys are shown once, expire after 30, 90, or 365 days, and are limited to 120 requests per minute.","contact":{"name":"Directoryz support","url":"https://directoryz.app/support"}},"servers":[{"url":"https://api.directoryz.app","description":"Production"}],"tags":[{"name":"Directories","description":"Create and manage workspace directories."},{"name":"Listings","description":"Create and manage listings within a directory."}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/directories":{"get":{"tags":["Directories"],"operationId":"listDirectories","summary":"List directories","description":"Requires `directories:read` and viewer access.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"q","in":"query","description":"Search names and descriptions.","schema":{"type":"string","maxLength":120}},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","published"]}}],"responses":{"200":{"description":"A paginated directory list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectoryList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/UpstreamError"}}},"post":{"tags":["Directories"],"operationId":"createDirectory","summary":"Create a directory","description":"Requires `directories:write` and editor access. An omitted slug is generated and de-duplicated; an explicit conflicting slug returns 409.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectoryCreate"},"example":{"name":"AI tools","description":"A curated collection of AI products.","status":"draft"}}}},"responses":{"201":{"description":"Directory created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectoryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/UpstreamError"}}}},"/api/v1/directories/{directoryId}":{"get":{"tags":["Directories"],"operationId":"getDirectory","summary":"Get a directory","description":"Requires `directories:read` and viewer access.","parameters":[{"name":"directoryId","in":"path","required":true,"description":"Directory UUID","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Directory details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectoryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/UpstreamError"}}},"patch":{"tags":["Directories"],"operationId":"updateDirectory","summary":"Update a directory","description":"Requires `directories:write` and editor access. Only supplied fields are changed.","parameters":[{"name":"directoryId","in":"path","required":true,"description":"Directory UUID","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectoryUpdate"},"example":{"status":"published","seo_title":"The best AI tools"}}}},"responses":{"200":{"description":"Directory updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectoryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/UpstreamError"}}},"delete":{"tags":["Directories"],"operationId":"deleteDirectory","summary":"Delete a directory","description":"Requires `directories:write` and owner access. This permanently deletes the directory and its listings.","parameters":[{"name":"directoryId","in":"path","required":true,"description":"Directory UUID","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Directory deleted."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/UpstreamError"}}}},"/api/v1/directories/{directoryId}/listings":{"get":{"tags":["Listings"],"operationId":"listListings","summary":"List listings","description":"Requires `listings:read` and viewer access.","parameters":[{"name":"directoryId","in":"path","required":true,"description":"Directory UUID","schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"q","in":"query","description":"Search listing content, tags, and custom values.","schema":{"type":"string","maxLength":120}},{"name":"category","in":"query","schema":{"type":"string","maxLength":80}},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","published"]}},{"name":"featured","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"A paginated listing list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/UpstreamError"}}},"post":{"tags":["Listings"],"operationId":"createListing","summary":"Create a listing","description":"Requires `listings:write` and editor access. The request is validated against the directory's custom listing fields.","parameters":[{"name":"directoryId","in":"path","required":true,"description":"Directory UUID","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingCreate"},"example":{"name":"Example product","website_url":"https://example.com","category":"Productivity","tags":["AI","SaaS"],"status":"published"}}}},"responses":{"201":{"description":"Listing created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/UpstreamError"}}}},"/api/v1/directories/{directoryId}/listings/{listingId}":{"get":{"tags":["Listings"],"operationId":"getListing","summary":"Get a listing","description":"Requires `listings:read` and viewer access.","parameters":[{"name":"directoryId","in":"path","required":true,"description":"Directory UUID","schema":{"type":"string","format":"uuid"}},{"name":"listingId","in":"path","required":true,"description":"Listing UUID","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Listing details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/UpstreamError"}}},"patch":{"tags":["Listings"],"operationId":"updateListing","summary":"Update a listing","description":"Requires `listings:write` and editor access. The slug changes only when explicitly supplied.","parameters":[{"name":"directoryId","in":"path","required":true,"description":"Directory UUID","schema":{"type":"string","format":"uuid"}},{"name":"listingId","in":"path","required":true,"description":"Listing UUID","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingUpdate"},"example":{"featured":true,"short_description":"Updated description"}}}},"responses":{"200":{"description":"Listing updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/UpstreamError"}}},"delete":{"tags":["Listings"],"operationId":"deleteListing","summary":"Delete a listing","description":"Requires `listings:write` and editor access.","parameters":[{"name":"directoryId","in":"path","required":true,"description":"Directory UUID","schema":{"type":"string","format":"uuid"}},{"name":"listingId","in":"path","required":true,"description":"Listing UUID","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Listing deleted."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"502":{"$ref":"#/components/responses/UpstreamError"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Directoryz API key","description":"A `dz_live_...` API key created in Workspace API settings."}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The key lacks the required permission or role.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The resource does not exist in the key's workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"A supplied slug is already in use or the workspace has reached an active-key limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PayloadTooLarge":{"description":"The request body exceeds the maximum size.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"The API key exceeded 120 requests per minute.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"An unexpected server error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UpstreamError":{"description":"An upstream provider operation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","details"],"properties":{"code":{"type":"string","examples":["validation_error"]},"message":{"type":"string"},"details":{"type":"array","items":{}}}}}},"Pagination":{"type":"object","required":["page","limit","total","pages"],"properties":{"page":{"type":"integer","minimum":1},"limit":{"type":"integer","minimum":1,"maximum":100},"total":{"type":"integer","minimum":0},"pages":{"type":"integer","minimum":1}}},"Directory":{"type":"object","required":["id","name","slug","status","public_url","listing_count","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string"},"accent":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"background":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"layout":{"type":"string","enum":["grid","list"]},"status":{"type":"string","enum":["draft","published"]},"seo_title":{"type":"string"},"seo_description":{"type":"string"},"website_url":{"type":"string"},"logo_url":{"type":["string","null"],"format":"uri"},"public_url":{"type":"string","format":"uri"},"listing_fields":{"type":"array","items":{"type":"object","additionalProperties":true}},"listing_count":{"type":"integer","minimum":0},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"DirectoryCreate":{"type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","minLength":2,"maxLength":80},"slug":{"type":"string","maxLength":64},"description":{"type":"string","maxLength":320},"accent":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"background":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"layout":{"type":"string","enum":["grid","list"]},"status":{"type":"string","enum":["draft","published"]},"seo_title":{"type":"string","maxLength":70},"seo_description":{"type":"string","maxLength":170},"website_url":{"type":"string","format":"uri","maxLength":500}}},"DirectoryUpdate":{"type":"object","minProperties":1,"additionalProperties":false,"properties":{"name":{"type":"string","minLength":2,"maxLength":80},"slug":{"type":"string","maxLength":64},"description":{"type":"string","maxLength":320},"accent":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"background":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"layout":{"type":"string","enum":["grid","list"]},"status":{"type":"string","enum":["draft","published"]},"seo_title":{"type":"string","maxLength":70},"seo_description":{"type":"string","maxLength":170},"website_url":{"type":"string","format":"uri","maxLength":500}}},"Listing":{"type":"object","required":["id","directory_id","name","slug","tags","featured","status","custom_values","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"directory_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"short_description":{"type":"string"},"description":{"type":"string"},"website_url":{"type":"string"},"image_url":{"type":["string","null"],"format":"uri"},"icon_url":{"type":"string"},"category":{"type":"string"},"location":{"type":"string"},"tags":{"type":"array","items":{"type":"string"},"maxItems":12},"featured":{"type":"boolean"},"status":{"type":"string","enum":["draft","published"]},"custom_values":{"type":"object","additionalProperties":{"type":["string","number","boolean"]}},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"ListingCreate":{"type":"object","required":["name"],"additionalProperties":false,"properties":{"name":{"type":"string","minLength":2,"maxLength":100},"slug":{"type":"string","maxLength":64},"short_description":{"type":"string","maxLength":180},"description":{"type":"string","maxLength":5000},"website_url":{"type":"string","format":"uri","maxLength":500},"icon_url":{"type":"string","format":"uri","maxLength":500},"category":{"type":"string","maxLength":80},"location":{"type":"string","maxLength":120},"tags":{"type":"array","items":{"type":"string","maxLength":30},"maxItems":12},"featured":{"type":"boolean"},"status":{"type":"string","enum":["draft","published"]},"custom_values":{"type":"object","additionalProperties":{"type":["string","number","boolean"]}}}},"ListingUpdate":{"type":"object","minProperties":1,"additionalProperties":false,"properties":{"name":{"type":"string","minLength":2,"maxLength":100},"slug":{"type":"string","maxLength":64},"short_description":{"type":"string","maxLength":180},"description":{"type":"string","maxLength":5000},"website_url":{"type":"string","format":"uri","maxLength":500},"icon_url":{"type":"string","format":"uri","maxLength":500},"category":{"type":"string","maxLength":80},"location":{"type":"string","maxLength":120},"tags":{"type":"array","items":{"type":"string","maxLength":30},"maxItems":12},"featured":{"type":"boolean"},"status":{"type":"string","enum":["draft","published"]},"custom_values":{"type":"object","additionalProperties":{"type":["string","number","boolean"]}}}},"DirectoryResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Directory"}}},"DirectoryList":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Directory"}},"meta":{"$ref":"#/components/schemas/Pagination"}}},"ListingResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Listing"}}},"ListingList":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"meta":{"$ref":"#/components/schemas/Pagination"}}}}}}