Quickstart
Four requests, in order — generate a key, find your directory, read its listings, create one. Everything here works with a key you can make in the next minute.
1. Generate a key
In the console, open Settings → API keys and choose Generate key. Pick the directory the key is for and tick what it may do. The secret is shown once, when you create it — copy it then, because we store only a hash of it and cannot show it again.
For this walkthrough, tick directories:read, listings:read and listings:write.
2. Find your directory
A key names exactly one directory, so this endpoint answers "which one am I pointed at". You need its id for every other request.
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)Take the id from the first row of data and use it wherever these pages write DIRECTORY_ID.
3. Read the listings
Listings come back in name order, a page at a time, with an envelope that tells you how many there are.
curl
curl -X GET \
-H "Authorization: Bearer YOUR_KEY" \
"https://directories.prosvita.io/api/v1/directories/DIRECTORY_ID/listings?page=1&per_page=25"Ruby
require "net/http"
require "json"
uri = URI("https://directories.prosvita.io/api/v1/directories/DIRECTORY_ID/listings?page=1&per_page=25")
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)Response
{
"data": [
{
"id": "018f7c2a-0000-7000-8000-0000000000c2",
"public_id": "9834hd7",
"slug": "my-cool-cafe",
"name": "My Cool Cafe",
"description": "Third-wave coffee in Kreuzberg.",
"website_url": "https://mycoolcafe.example",
"status": "published",
"verification_status": "verified",
"primary_category": {
"id": "018f7c2a-0000-7000-8000-0000000000a1",
"name": "Cafes",
"path": "food/cafes"
},
"tags": [
"wifi",
"outdoor-seating"
],
"properties": {
"opening_hours": "9-5"
},
"created_at": "2026-08-01T09:14:22Z",
"updated_at": "2026-08-27T11:02:05.418291Z",
"content_updated_at": "2026-08-27T11:02:05Z"
}
],
"meta": {
"page": 1,
"per_page": 25,
"count": 412,
"pages": 17
}
}4. Create a listing
A new listing starts as a draft, so nothing goes live by accident. name is the only field you have to send.
curl
curl -X POST \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "My Cool Cafe",
"website_url": "https://mycoolcafe.example",
"description": "Third-wave coffee in Kreuzberg.",
"primary_category_id": "018f7c2a-0000-7000-8000-0000000000a1",
"tags": [
"wifi",
"outdoor-seating"
]
}' \
"https://directories.prosvita.io/api/v1/directories/DIRECTORY_ID/listings"Ruby
require "net/http"
require "json"
uri = URI("https://directories.prosvita.io/api/v1/directories/DIRECTORY_ID/listings")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_KEY"
request["Content-Type"] = "application/json"
request.body = {
"name" => "My Cool Cafe",
"website_url" => "https://mycoolcafe.example",
"description" => "Third-wave coffee in Kreuzberg.",
"primary_category_id" => "018f7c2a-0000-7000-8000-0000000000a1",
"tags" => ["wifi", "outdoor-seating"]
}.to_json
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts JSON.parse(response.body)To put it on the public site, POST to the listing's publish path. A draft needs a primary category first, and your plan's listing limit is checked at that moment.