Directories
A key names exactly one directory. These three endpoints read it and change the settings the console's own screens change.
The directory object
One object, carrying the directory's identity, its publishing state and its whole linkback policy.
Fields
| Field | Type | Description |
|---|---|---|
| id | string | The directory's uuid. |
| slug | string | The directory's URL segment. |
| name | string | The directory's name. |
| description | string | What the directory lists. |
| status | string | Whether the directory is live. |
| default_locale | string | The locale the directory publishes in. |
| first_published_at | string | When the directory first went live, or null. |
| listings_count | integer | How many listings the directory holds. This is the number your plan's limit is checked against. |
| check_frequency | string | How often every linkback is re-checked. |
| enforcement_action | string | What happens to a listing whose linkback stays broken. |
| grace_period_days | integer | How long a broken linkback has before that applies. |
| linkback_match_mode | string | How a linkback is matched. Read-only — exact_url is the only mode implemented. |
| notify_owner | boolean | Whether the listed business is emailed when its linkback breaks. |
| public_linkback_badge | boolean | Whether visitors see linkback health. |
| submission_mode | string | Whether the public site accepts new entries. |
| claim_mode | string | Whether a business may claim its own listing. |
| created_at | string | When the directory was created. |
| updated_at | string | When the directory last changed, to the microsecond. |
Response
{
"data": {
"id": "018f7c2a-0000-7000-8000-00000000000d",
"slug": "berlin-cafes",
"name": "Berlin Cafes",
"description": "Every independent cafe in Berlin, checked weekly.",
"status": "live",
"default_locale": "en",
"first_published_at": "2026-06-14T08:00:00Z",
"listings_count": 412,
"check_frequency": "weekly",
"enforcement_action": "unpublish",
"grace_period_days": 14,
"linkback_match_mode": "exact_url",
"notify_owner": true,
"public_linkback_badge": false,
"submission_mode": "open",
"claim_mode": "email",
"created_at": "2026-06-01T10:22:00Z",
"updated_at": "2026-08-27T09:41:12.882104Z"
}
}
List directories
GET /api/v1/directories
directories:read The capability a key must carry to call this.
List the directory this key was issued for. One key names exactly one directory, so this answers "which one am I pointed at".
curl
curl -X GET \
-H "Authorization: Bearer YOUR_KEY" \
"https://directories.prosvita.io/api/v1/directories"Ruby
require "net/http"
require "json"
uri = URI("https://directories.prosvita.io/api/v1/directories")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer YOUR_KEY"
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts JSON.parse(response.body)Read a directory
GET /api/v1/directories/DIRECTORY_ID
directories:read The capability a key must carry to call this.
Read one directory — its name, its description and its whole linkback policy.
curl
curl -X GET \
-H "Authorization: Bearer YOUR_KEY" \
"https://directories.prosvita.io/api/v1/directories/DIRECTORY_ID"Ruby
require "net/http"
require "json"
uri = URI("https://directories.prosvita.io/api/v1/directories/DIRECTORY_ID")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer YOUR_KEY"
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts JSON.parse(response.body)Update a directory
PATCH /api/v1/directories/DIRECTORY_ID
directories:write The capability a key must carry to call this.
Change the directory's details or its linkback policy. Only the attributes below can be written.
Body parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | The directory's name, as it appears on its own site and in the console. |
| description | string | One or two sentences about what the directory lists. |
| default_locale | string | The locale the directory publishes in, as a language code. |
| check_frequency | string | How often we re-check every linkback. Your plan decides which frequencies are available. |
| enforcement_action | string | What happens to a listing whose linkback is broken once its grace period runs out. |
| grace_period_days | integer | How many days a broken linkback has before the enforcement action applies. |
| notify_owner | boolean | Whether the listed business is emailed when its linkback breaks. |
| public_linkback_badge | boolean | Whether visitors see linkback health on the public site. Off by default — it is your data until you publish it. |
| expected_updated_at | string | The updated_at you last read, echoed back. If the record has moved since, nothing is written and you get 409 with the record as it now stands. Leave it out to write unconditionally. |
Everything not in the table is read-only, linkback_match_mode included. exact_url is the only mode implemented, so a directory set to anything else would stall every linkback check it runs; the field becomes writable the day the other modes ship.
Two settings are governed by your plan — check_frequency and enforcement_action. A value your plan does not allow is refused with plan_not_permitted, and only when you actually change it, so renaming a directory is never refused over a policy you did not touch.
curl
curl -X PATCH \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"grace_period_days": 21
}' \
"https://directories.prosvita.io/api/v1/directories/DIRECTORY_ID"Ruby
require "net/http"
require "json"
uri = URI("https://directories.prosvita.io/api/v1/directories/DIRECTORY_ID")
request = Net::HTTP::Patch.new(uri)
request["Authorization"] = "Bearer YOUR_KEY"
request["Content-Type"] = "application/json"
request.body = {
"grace_period_days" => 21
}.to_json
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts JSON.parse(response.body)