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.

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 for self-serve OAuth/API-key onboarding flows (not publicly available yet).
  • Escalate to direct contact when integration scope requires private systems or custom SLA terms.

Authentication and access

OAuth 2.0 discovery metadata is published for agent interoperability at /.well-known/oauth-authorization-server with PKCE S256 support and scoped permissions.

Scoped permissions are standardized and documented in OAuth metadata. Canonical scope metadata is published in /.well-known/oauth-protected-resource and in openapi.json (`x-scopes-supported` and OAuth2 security scheme).

  • 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: discover auth metadata first from /.well-known/oauth-protected-resource , load authorization server metadata from /.well-known/oauth-authorization-server , map scope expectations from openapi.json, then execute least-privilege calls.

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).

  • 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_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.

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.

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.