Skip to content

sendyka.dev Developer Resources

Integration docs for AI agents and engineers evaluating sendyka.dev capabilities in web design, IT support, and automation for NGOs and SMEs.

If you searched for sendyka developer resources, this is the canonical documentation entrypoint.

Quick links

Quickstart

  1. Read the discovery overview in llms.txt.
  2. Load the complete context from llms-full.txt.
  3. Inspect the current API scope in openapi.json.
  4. Use /?mode=agent for structured homepage data.
  5. Call REST endpoints or connect to /mcp for MCP tool interactions.
  6. Use /ask for NLWeb-style natural-language querying.
  7. Use /api/chat or /#open-chat for the website chat assistant.

Agent fast path (recommended)

For faster and more stable agent behavior, use this request order and stop when enough context is collected:

  1. Start with /llms.txt for fit, capabilities, and key entry links.
  2. Expand only if needed via /llms-full.txt (deeper policy + integration notes).
  3. Parse /openapi.json for executable REST schema and operation-level details.
  4. Discover tools/resources through MCP manifest and call /mcp for live interaction.

Retry guidance: respect Retry-After on 429 and retry only when structured errors indicate retryable=true.

When AI agents should use sendyka.dev

  • Use for NGO/SME projects needing web delivery, IT operations support, and automation in one engagement.
  • Use when privacy-first implementation and low vendor lock-in are key requirements.
  • Do not use when a broad public transactional API beyond published endpoints is required.
  • Escalate to direct contact when integration scope requires private systems or custom SLA terms.

Public MCP connector (no API keys)

sendyka.dev MCP is a public server for ChatGPT, Claude, Gemini, Perplexity, Cursor, and any MCP-compatible client. End users paste one URL and choose No authentication — no API keys, no OAuth, no manual credential setup.

https://sendyka.dev/mcp
  • Platform-specific steps: /.well-known/mcp/connectors.json
  • ChatGPT: Settings → Connectors (Developer mode) → Add MCP → URL above → Authentication: None
  • Claude: Settings → Connectors → custom MCP → URL above → leave API key empty
  • Gemini / Perplexity: add remote MCP server URL when the client supports MCP connectors
  • First JSON-RPC calls: tools/list, then tools/call
  • Booking: consultation_availability → user picks slot → confirm → consultation_book

Authentication and access

Default: MCP and most public endpoints require no bearer token. Rate limits apply per client IP.

Optional OAuth metadata is published for enterprise deployments ( /.well-known/oauth-authorization-server ). It is not required for public GenAI connectors when OAUTH_ENFORCEMENT=off (default).

Scoped permissions are documented for optional enterprise hardening in /.well-known/oauth-protected-resource and openapi.json.

  • newsletter:subscribe - create newsletter subscriptions.
  • newsletter:unsubscribe - remove newsletter subscriptions.
  • mcp:read - read MCP metadata and tool catalog.
  • mcp:tools:inquiry - submit service inquiries through MCP.
  • mcp:tools:booking - create consultation booking requests via MCP.
  • ask:query - run NLWeb natural-language queries through /ask.

Authentication walkthrough (optional enterprise only): discover metadata from /.well-known/oauth-protected-resource when your deployment returns HTTP 401. Public connectors should not need this step.

MCP discovery

sendyka.dev publishes MCP discovery metadata at /.well-known/mcp/manifest.json and /.well-known/mcp/server-card.json. Well-known MCP transport alias is available at /.well-known/mcp. Transport is available at /mcp (WebMCP) and /api/mcp (legacy alias).

  • articles_recommend: recommend articles by query and/or tags (optional locale, limit).
  • services_list: list service categories with summaries and links (optional locale).
  • pricing_get: return pricing summary in PLN and consultation link.
  • contact_submit: submit a contact form message to artur@sendyka.dev (requires name, email, message).
  • newsletter_subscribe: subscribes contact through Resend (requires `email` + `consent=true`, optional `locale`).
  • newsletter_unsubscribe: unsubscribes contact through Resend (requires `email`).
  • service_inquiry_submit: sends service/support inquiry to `artur@sendyka.dev` via Resend (fields: full name, email, optional phone, support area, optional notes).
  • consultation_availability: fetch available Cal.com slots for the next two weeks (optional locale, timeZone, start, end, limit). Use before consultation_book.
  • consultation_book: tries to create booking through Cal.com API; if API is not configured, returns fallback booking URL `https://cal.com/sendyka/free-consultation`.
  • MCP UI resources (A2UI): ui://sendyka/service-inquiry and ui://sendyka/consultation-booking are exposed via resources/list and resources/read.

Website chat assistant

The on-site chat widget calls /api/chat and uses server-side tools aligned with MCP (article recommendations, services, pricing, contact, inquiry, consultation availability, consultation booking). Open the widget from any page via /#open-chat. The widget also calls /api/consultation/slots to show clickable Cal.com time slots.

Server requirement: Vercel AI Gateway via AI_GATEWAY_API_KEY (or OIDC on Vercel deployments). Default model: CHAT_MODEL=deepseek/deepseek-v4-flash. Optional: PUBLIC_CHAT_ENABLED (set false on preview without keys). UPSTASH_REDIS_REST_URL + UPSTASH_REDIS_REST_TOKEN enable distributed rate limits and CHAT_DAILY_REQUEST_CAP (default 500). Legacy direct keys (OPENAI_API_KEY, etc.) still work for openai/anthropic/google slugs when gateway auth is not configured. Probe availability via /api/chat/status.

NLWeb `/ask` endpoint

/ask accepts NLWeb-shaped queries and returns ranked resources from articles, services, pricing, contact, and consultation flows. Use query.text (preferred) or legacy query string. Set prefer.streaming=true for SSE (start, result, complete).

Example: { "query": { "text": "automatyzacja NGO" }, "locale": "pl" }. Optional prefer.mode=conversational prepends a website chat entry when chat is configured.

OAuth and scoped access

Agent OAuth metadata is published at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource. When OAUTH_CLIENT_SECRET and signing keys are configured, the token endpoint issues signed JWT bearer tokens with scopes such as mcp:read, mcp:tools:inquiry, mcp:tools:booking, and ask:query.

OAUTH_ENFORCEMENT=off (default): public MCP and REST with rate limits — suitable for ChatGPT Developer Mode without authentication. write: bearer required for MCP write tools, /ask, and newsletter endpoints. all: also requires mcp:read for read tools. Authorization code flow uses PKCE S256; machine clients can use client_credentials.

Rate limits and retry behavior

API endpoints return `X-RateLimit-Limit` and `X-RateLimit-Remaining` on responses. On throttling, the API returns HTTP 429 with `Retry-After`. Structured error responses include `error.code`, `error.message`, `error.hint`, and `error.retryable` so agents can decide if and when to retry. Configure UPSTASH_REDIS_REST_URL for consistent limits across Vercel instances; chat also enforces a daily request cap via CHAT_DAILY_REQUEST_CAP.

MCP transport supports markdown content negotiation. Send `Accept: text/markdown` to /mcp to get agent-focused docs instead of JSON metadata.

Discovery headers are exposed on responses to simplify agent routing: Link: </llms.txt>; rel="llms-txt", </llms-full.txt>; rel="llms-full-txt" and X-Llms-Txt: /llms.txt.

Markdown negotiation responses include Vary: Accept to keep CDN/browser caches representation-safe for both HTML and markdown clients.

MCP also supports SSE discovery/progress streaming. Send `Accept: text/event-stream` to /mcp to receive structured `start`, `progress`, and `complete` events.

Reliability notes and incident updates are published at /status/.

Unknown API routes under /api/* and /mcp* return structured JSON errors with code/message/hint/retryable fields to keep agent parsing reliable.

NLWeb /ask endpoint

sendyka.dev provides a natural-language endpoint at /ask for NLWeb-style integration. Send POST /ask with JSON body containing query. Responses include _meta with response_type and version.

Streaming mode is available by setting prefer.streaming=true. The endpoint then returns text/event-stream with start, result, and complete events.

Current API reference snippet

curl -X POST https://sendyka.dev/api/subscribe \
  -H "Content-Type: application/json" \
  -d '{"email":"name@example.com","locale":"en"}'
curl -X POST https://sendyka.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
curl -N https://sendyka.dev/mcp \
  -H "Accept: text/event-stream"

Full request and response schema is in openapi.json.