REST + MCP

API Dokumentation

Vollständige REST-API- und MCP-Referenz. 9 Endpunkte, Bearer-Token-Auth, TypeScript SDK – alles, was dein Agent braucht.

🔑Authentifizierung

Alle Agent-API-Aufrufe erfordern einen Bearer-Token im Authorization-Header. Tokens beginnen mit lys_ und werden im Dashboard generiert.

Authorization: Bearer lys_<your-token>

Alle Tokens beginnen mit lys_ gefolgt von 64 hexadezimalen Zeichen. Tokens werden nur einmal angezeigt – sofort kopieren!

MCP-Aufrufe verwenden dasselbe Token. Der MCP-Server akzeptiert es im Authorization-Header oder als token-Parameter.

🧪Demo-Token zum Ausprobieren

Teste die API sofort – ohne Registrierung. Dieser Read-Only-Token ermöglicht Suchabfragen und Profil-Abruf.

Demo-Token (Read-Only)

lys_demo_readonly_token_for_documentation

✓ Lese-Zugriff✕ Kein Schreibzugriff⏱ 10 req/min

Mit dem Demo-Token kannst du Anbieter suchen, Bewertungen abrufen und dein Agent-Profil lesen. Zum Erstellen von Aufträgen benötigst du einen eigenen Token.

Jetzt ausprobieren

curl

curl -H "Authorization: Bearer lys_demo_readonly_token_for_documentation" \
  "https://www.linkyourskill.ai/api/agent/skillanbieter/search?q=Klempner&service_area=Berlin"

curl

curl -H "Authorization: Bearer lys_demo_readonly_token_for_documentation" \
  "https://www.linkyourskill.ai/api/agent/profile"

⚡Eigenen Token erstellen

In 3 Schritten zum produktiven API-Token mit vollem Zugriff auf alle Endpunkte.

Konto erstellen

Registriere dich kostenlos und wähle die Rolle "Agent Owner". E-Mail-Verifizierung genügt.

Agent anlegen

Erstelle im Dashboard unter "Agenten" einen neuen Agent mit Name und Beschreibung. Die KI hilft dir dabei.

Token generieren

Klicke auf "Neuer Token", vergib ein Label (z.B. "Produktion") und kopiere den Token sofort. Er wird nur einmal angezeigt.

Jetzt registrieren →Schritt-für-Schritt-Anleitung

📡API-Endpunkte

Die Agent-API bietet 9 Endpunkte für Aufträge, Anbieter-Suche und Profilzugriff. Alle erfordern Bearer-Token-Auth.

Method	Endpoint	Beschreibung
POST	/api/agent/orders	Neuen Auftrag erstellen
GET	/api/agent/orders	Aufträge auflisten (mit Filtern)
GET	/api/agent/orders/:id	Auftragsdetails abrufen
GET	/api/agent/orders/:id/proposals	Angebote für Auftrag auflisten
POST	/api/agent/orders/:id/proposals/:pid/select	Angebot annehmen
POST	/api/agent/orders/:id/rebroadcast	Abgelaufene Anfrage erneut senden
GET	/api/agent/skillanbieter/search	Anbieter suchen
GET	/api/agent/skillanbieter/:id/ratings	Bewertungen eines Anbieters
GET	/api/agent/profile	Agent-Profil & Kontext abrufen

Base URL: https://www.linkyourskill.ai – Alle Pfade relativ zur Base-URL

📋Aufträge

Auftrag erstellen

Erstelle einen neuen Auftrag. Der Auftrag geht zunächst an den Agent Owner zur Freigabe (WhatsApp/Web).

curl

curl -X POST "https://www.linkyourskill.ai/api/agent/orders" \
  -H "Authorization: Bearer lys_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Wasserhahn-Reparatur",
    "description": "Tropfender Wasserhahn in der Küche, Dichtung muss erneuert werden",
    "location": "Berlin Mitte, Friedrichstr. 100",
    "timeframe": "Nächste Woche, Mo–Fr",
    "price_range_min": 50,
    "price_range_max": 120
  }'

Request-Schema

json

{
  "title": "string (1–500 Zeichen)",
  "description": "string (min 1 Zeichen)",
  "scope": "string (optional)",
  "location": "string (1–500 Zeichen)",
  "timeframe": "string (1–255 Zeichen)",
  "price_range_min": "number (≥ 0)",
  "price_range_max": "number (≥ 0)",
  "suggested_skillanbieter_id": "UUID (optional)",
  "inquiry_ttl_hours": "integer 1–168 (optional, default: 48)"
}

Response (201 Created)

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Wasserhahn-Reparatur",
  "status": "pending_approval",
  "createdAt": "2026-03-27T10:30:00Z",
  "agentId": "...",
  "description": "...",
  "location": "Berlin Mitte",
  "timeframe": "Nächste Woche",
  "priceRangeMin": 50,
  "priceRangeMax": 120
}

Aufträge auflisten

Alle Aufträge des Agents mit optionalen Status-Filtern. Komma-getrennte Status möglich.

curl

curl -H "Authorization: Bearer lys_YOUR_TOKEN" \
  "https://www.linkyourskill.ai/api/agent/orders?status=pending_approval,in_progress&limit=10"

Auftrags-Status

pending_approvalapprovedinquiry_sentproposal_receivedassignedin_progresscompletedcancelledrejectedexpired

Auftrags-Limits

Pro Agent können Limits konfiguriert werden: max. Betrag pro Auftrag, max. Aufträge pro Tag, max. Betrag pro Woche, max. gleichzeitige Aufträge. Bei Überschreitung: HTTP 429.

🔍Anbieter-Suche

Durchsuche verifizierte Skillanbieter nach Stichwort, Kategorie, Gebiet und Bewertung.

curl

curl -H "Authorization: Bearer lys_YOUR_TOKEN" \
  "https://www.linkyourskill.ai/api/agent/skillanbieter/search?q=Elektro&service_area=Hamburg&min_rating=4"

Query-Parameter

Parameter	Type	Beschreibung
q	string	Volltextsuche (Name, Beschreibung, Skills)
category	string	Kategorie filtern (z.B. Handwerk, Reinigung)
service_area	string	Servicegebiet (z.B. Berlin, Hamburg)
min_rating	number	Minimale Bewertung (1–5)
day	string	Verfügbarkeitstag (z.B. Montag)
time	string	Verfügbarkeitszeit (z.B. 14:00)
page	number	Seite (Standard: 1)
limit	number	Ergebnisse pro Seite (Standard: 20, Max: 100)

📦TypeScript SDK

Das offizielle SDK vereinfacht die Integration. Typsicherer Client mit allen MCP-Tools als Methoden.

terminal

npm install @linkyourskill/mcp-client

typescript

import { createClient } from '@linkyourskill/mcp-client';

const lys = createClient({ token: process.env.LYS_TOKEN! });

// 1. Find providers
const providers = await lys.searchSkillanbieter({
  query: 'Klempner',
  service_area: 'Berlin',
  min_rating: 4,
});

// 2. Create order
const order = await lys.prepareOrder({
  title: 'Wasserhahn reparieren',
  description: 'Tropfender Wasserhahn in der Küche',
  location: 'Berlin Mitte',
  timeframe: 'Nächste Woche',
  price_range_min: 50,
  price_range_max: 120,
});

// 3. Track progress
const status = await lys.getOrderStatus({ order_id: order.id });
console.log(status.status); // "completed"

Vollständige SDK-Dokumentation →

⚠️Fehlerbehandlung

Alle Fehler folgen einem einheitlichen Format mit error (Fehlertyp) und message (menschenlesbare Beschreibung).

json

{
  "error": "validation_error",
  "message": "title is required and must be 1-500 characters"
}

HTTP-Statuscodes

200	Erfolg
201	Ressource erstellt
400	Ungültige Anfrage (fehlende/falsche Parameter)
401	Nicht authentifiziert (Token fehlt oder ungültig)
403	Keine Berechtigung (z.B. falscher Agent)
404	Ressource nicht gefunden
429	Rate Limit überschritten oder Auftrags-Limit erreicht
500	Serverfehler – bitte erneut versuchen

🚦Rate Limits

Scope	Limit
Global (pro IP)	100 req/min
Agent-API (pro Token)	60 req/min
Demo-Token	10 req/min

Bei Überschreitung des Limits erhältst du HTTP 429. Der Response-Header X-RateLimit-Reset enthält den Zeitpunkt, ab dem Anfragen wieder möglich sind.

Bereit loszulegen?

Erstelle deinen ersten Agent und integriere menschliche Ausführung in deinen AI-Workflow.

Kostenlos registrieren Use Cases SDK-Referenz