geoludek
Sprawdź działkę

Dokumentacja API

Publiczne, wersjonowane API do czytania i zmieniania danych Twojego konta z własnego kodu. Uwierzytelnianie kluczem API, limity liczone per klucz.

Opisy endpointów są po angielsku — tak samo jak treści błędów, które zwraca API.

Adres bazowy https://api.geoludek.com/api/public/v1 Wersja v1

Uwierzytelnianie

Every request needs an API key, created in the dashboard under API keys. Send it in the Authorization header as a bearer token; X-API-Key is accepted as an alternative. The key is shown once, when it is created, and cannot be recovered afterwards — only revoked and replaced. Never put one in browser code or a public repository: a key carries the full authority of the scopes it was given.

Authorization 
Authorization: Bearer gld_k1a2b3c4d5e6_EXAMPLEoNLYdoNOTuSEtHISkEYiNaNYtHING0000
Utwórz klucz API w panelu →

Uprawnienia

Każdy klucz nosi listę uprawnień, a każdy endpoint wymaga jednego z nich. Klucz bez odpowiedniego uprawnienia dostaje odpowiedź 403.

account:read
Read the account's profile, plan and usage.
files:read
List stored files and get temporary download links.
tickets:read
Read support tickets and their messages.
tickets:write
Open support tickets and reply to them.

Limity

Limits are counted per key, in a fixed one-minute window. Some endpoints cost more than one request against that budget; each one says so below. Every response carries the headers above, so a client can pace itself without waiting to be refused. A refusal is a 429 with Retry-After set to the seconds remaining in the window.

Domyślnie 60 żądań na minutę na klucz.

  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset
  • Retry-After

Endpointy

GET /api/public/v1/me

Get the account this key belongs to

Identifies the account behind the key, and reports what the key itself is allowed to do. Useful as a connectivity check when setting an integration up: if this returns 200, authentication is working, and the `key` object tells you which scopes you actually have and what your rate limit is.

Wymaga account:read Koszt: 1
curl 
curl "https://api.geoludek.com/api/public/v1/me" \
  -H "Authorization: Bearer $GEOLUDEK_API_KEY"

Przykładowa odpowiedź

{
  "account": {
    "created_at": "2026-01-14T09:12:44Z",
    "credits": 120,
    "email": "[email protected]",
    "id": "9a4c1e1e-2f77-4c1a-9a4e-1f0b7d3e5c21",
    "role": "user",
    "user_name": "you"
  },
  "key": {
    "created_at": "2026-09-01T11:02:10Z",
    "expires_at": null,
    "id": "gld_k1a2b3c4d5e6_••••••••",
    "last_used_at": "2026-09-12T08:41:02Z",
    "name": "Production worker",
    "rate_limit": 60,
    "scopes": [
      "account:read",
      "files:read"
    ]
  }
}
GET /api/public/v1/files

List the account's files

Returns the files stored on this account, newest first, each with a temporary download link. Links are presigned and expire within the hour, so fetch a file soon after listing it rather than storing the URL. Requires file storage to be configured on the server; without it this endpoint answers 503 with `FEATURE_UNAVAILABLE`.

Wymaga files:read Koszt: 2

Parametry

limit integer
How many to return, 1–100. Domyślnie: 20.
offset integer
How many to skip, for paging. Domyślnie: 0.
purpose string
Narrow to one purpose, e.g. `chat` for images sent to the assistant. Omit for all.
curl 
curl "https://api.geoludek.com/api/public/v1/files?limit=50&offset=20&purpose=chat" \
  -H "Authorization: Bearer $GEOLUDEK_API_KEY"

Przykładowa odpowiedź

{
  "files": [
    {
      "content_type": "application/pdf",
      "created_at": "2026-09-10T14:22:01Z",
      "filename": "invoice.pdf",
      "id": "2f5a9c33-7b1d-4e0a-8c62-9d41f0a7b3e8",
      "purpose": "general",
      "size": 182344,
      "url": "https://files.example.com/…?X-Amz-Expires=3600&…"
    }
  ],
  "limit": 20,
  "offset": 0,
  "total": 2
}

Może też zwrócić: FEATURE_UNAVAILABLE

POST /api/public/v1/tickets

Open a support ticket

Creates a support ticket on the account, exactly as the dashboard would. This is the endpoint for wiring your own monitoring or an internal tool into support: raise a ticket from the system that noticed the problem. The account's open-ticket limit applies, so this can answer 409 with `TICKET_LIMIT` — close one before opening another. Support is part of some plans and not others; on a plan without it this answers 403 with `FEATURE_LOCKED`.

Wymaga tickets:write Koszt: 10

Parametry

subject string wymagany
One line saying what this is about.
body string wymagany
The message itself.
category string
Which queue it belongs in. Domyślnie: other.
email_on_reply boolean
Email the account when support replies. Domyślnie: true.
curl 
curl -X POST "https://api.geoludek.com/api/public/v1/tickets" \
  -H "Authorization: Bearer $GEOLUDEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject":"Webhook deliveries failing","body":"Since 09:00 UTC every delivery returns 504.","category":"technical","email_on_reply":true}'

Przykładowa odpowiedź

{
  "ticket": {
    "category": "technical",
    "created_at": "2026-09-12T09:03:11Z",
    "id": "c1f0a7b3-9d41-4e0a-8c62-2f5a9c337b1d",
    "last_message_at": "2026-09-12T09:03:11Z",
    "status": "open",
    "subject": "Webhook deliveries failing"
  }
}

Może też zwrócić: TICKET_LIMIT,FEATURE_LOCKED,INVALID_PARAMS

Błędy

Każdy błąd ma ten sam kształt: pole z treścią dla człowieka i stabilny kod błędu. Rozgałęziaj swój kod na err_code, nigdy na treść komunikatu.

API_KEY_MISSING 401

No key was sent.

API_KEY_INVALID 401

The key is malformed, unknown, revoked or expired. The four are not distinguished on purpose.

API_KEY_SCOPE 403

The key is valid but was not granted the scope this endpoint requires.

RATE_LIMIT_EXCEEDED 429

This key's per-minute budget is spent. Wait for Retry-After seconds.

INVALID_PARAMS 400

A parameter was missing or out of range.

NOT_FOUND 404

The requested resource does not exist, or does not belong to this key's account.

FEATURE_UNAVAILABLE 503

The endpoint depends on something this server has not configured, such as file storage.

INTERNAL_ERROR 500

Something failed on our side. Safe to retry.

Pliki cookie

Używamy tylko tych, które są niezbędne do działania serwisu. Możesz zgodzić się także na opcjonalne. Szczegóły

plen