# API Overview और Base URL

Synapse API एक RESTful HTTP API है। सभी एंडपॉइंट्स JSON लौटाते हैं (जहाँ उल्लेख किया गया है वहाँ को छोड़कर)। यह पृष्ठ विशिष्ट एंडपॉइंट्स में गोता लगाने से पहले आवश्यक मूल बातें कवर करता है।

## Base URL

```
https://synapse.schaefer.zone
```

इस दस्तावेज़ीकरण के सभी पाथ इस base URL के सापेक्ष हैं। सेल्फ-होस्टेड इंस्टेंस के लिए, अपने स्वयं के URL से बदलें।

## प्रमाणीकरण

दो विधियाँ, दोनों `Authorization` हेडर के माध्यम से भेजी जाती हैं:

```
Authorization: Bearer YOUR_MIND_KEY    # for data endpoints
Authorization: Bearer YOUR_JWT          # for account endpoints
```

या क्वेरी पैरामीटर के माध्यम से — **डिफ़ॉल्ट रूप से अक्षम** (`AUTH_QUERY_KEY_MODE=deny`, हार्डन्ड डिफ़ॉल्ट;
सर्वर 401 और संकेत "Query-param auth (?key=) is disabled" के साथ उत्तर देता है)। केवल स्पष्ट `allow` मोड में यह
60/min तक सीमित संक्रमण वाल्व के रूप में काम करता है — देखें [प्रमाणीकरण](/docs/getting-started/authentication):

```
?key=YOUR_MIND_KEY
```

विवरण के लिए [प्रमाणीकरण](/docs/getting-started/authentication) देखें।

## एंडपॉइंट समूह

| समूह | प्रमाणीकरण | विवरण |
|-------|------|-------------|
| Public | कोई नहीं | लैंडिंग पृष्ठ, स्वास्थ्य, OpenAPI, दस्तावेज़ |
| Memory | Mind Key | CRUD, खोज, सिंक, एम्बेडिंग |
| Chat | Mind Key / JWT | मानव और एजेंट के बीच अतुल्यकालिक मैसेजिंग |
| Tasks | Mind Key | कार्य प्रबंधन |
| Scripts | Mind Key / JWT | स्थायी स्क्रिप्ट स्टोर |
| Scheduler | Mind Key | Cron कार्य + वेरिएबल्स |
| Webhooks | Mind Key | घटनाओं पर HTTP कॉलबैक |
| Computers | Mind Key / JWT | रिमोट कंप्यूटर नियंत्रण |
| User/Minds | JWT | खाता + mind प्रबंधन |
| Sharing | JWT | उपयोगकर्ताओं के बीच mind साझाकरण |
| Push | JWT | Web Push सब्सक्रिप्शन |
| Tools | कोई नहीं | समय, calc, random (सार्वजनिक उपयोगिताएँ) |

## प्रतिक्रिया प्रारूप

- **JSON** (डिफ़ॉल्ट): `{ "key": "value", ... }`
- **सादा टेक्स्ट**: `/memory/recall` LLM-अनुकूलित टेक्स्ट लौटाता है
- **HTML**: `/`, `/docs`, `/human`, `/support`, `/playground`

## मानक प्रतिक्रिया लिफ़ाफ़ा

सफलता प्रतिक्रियाएँ सीधे डेटा लौटाती हैं:

```json
{ "id": "mem_001", "status": "stored" }
```

त्रुटि प्रतिक्रियाएँ इस प्रारूप का उपयोग करती हैं:

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}
```

> [!NOTE]
> `docs` फ़ील्ड सामान्य त्रुटियों के लिए प्रासंगिक दस्तावेज़ीकरण से लिंक करता है।

## HTTP स्टेटस कोड

| कोड | अर्थ |
|------|---------|
| 200 | सफलता (GET, PUT) |
| 201 | बनाया गया (POST) |
| 204 | कोई सामग्री नहीं (DELETE) |
| 400 | खराब अनुरोध (सत्यापन त्रुटि) |
| 401 | अनधिकृत (गायब/अमान्य टोकन) |
| 403 | निषिद्ध (गलत टोकन प्रकार) |
| 404 | नहीं मिला (पाथ मौजूद नहीं है) |
| 409 | टकराव (डुप्लिकेट) |
| 429 | बहुत अधिक अनुरोध (रेट लिमिट) |
| 500 | सर्वर त्रुटि |

## खोज क्षमता एंडपॉइंट्स

| एंडपॉइंट | उद्देश्य |
|----------|---------|
| `GET /` | लैंडिंग पृष्ठ (LLM-अनुकूलित) |
| `GET /endpoints` | सभी एंडपॉइंट्स की मशीन-पठनीय सूची |
| `GET /endpoints?format=text` | सादे-टेक्स्ट एंडपॉइंट सूची |
| `GET /openapi.json` | OpenAPI 3.0 विशेषता |
| `GET /help` | पूर्ण API दस्तावेज़ीकरण (HTML) |
| `GET /help?format=json` | JSON के रूप में API दस्तावेज़ |
| `GET /docs` | दस्तावेज़ीकरण सिस्टम (HTML) |
| `GET /docs?format=json` | दस्तावेज़ीकरण सूचकांक (JSON) |
| `GET /docs?format=text&scope=all` | सभी दस्तावेज़ एक टेक्स्ट ब्लॉक के रूप में |
| `GET /playground` | इंटरैक्टिव API प्लेग्राउंड |

## रेट लिमिट

| प्रमाणीकरण विधि | सीमा |
|-------------|-------|
| Mind Key (हेडर) | 120/min बाहरी IPs से (प्रति पहचान); विश्वसनीय आंतरिक नेटवर्क के लिए असीमित |
| Mind Key (?key=, केवल allow पर) | प्रति IP 60/min |
| JWT (हेडर) | 120 req/min (बाहरी IPs; विश्वसनीय आंतरिक नेटवर्क के लिए असीमित) |
| सार्वजनिक एंडपॉइंट्स | कोई नहीं |

रेट-लिमिटेड प्रतिक्रियाएँ शामिल करती हैं:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
Retry-After: 30  (only when 429)
```

## पेजिनेशन

सूची एंडपॉइंट्स `?limit=` और `?offset=` का समर्थन करते हैं:

```
GET /memory?limit=50&offset=100
GET /mind/tasks?status=pending
```

डिफ़ॉल्ट सीमा: 100। अधिकतम सीमा: 500।

## CORS

सभी एंडपॉइंट्स ब्राउज़र-आधारित क्लाइंट्स के लिए CORS का समर्थन करते हैं:

```
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Synapse-JWT, Mcp-Session-Id, Mcp-Tool-Profile
```

## SDKs और क्लाइंट्स

- **Node.js SDK**: `npm install synapse-memory-sdk` ([repo](https://gitlab.com/schaefer-services/synapse-sdk-js))
- **MCP Server**: `npx -y synapse-mcp-api@latest` ([repo](https://gitlab.com/schaefer-services/synapse-mcp))
- **HTTP client**: कोई भी HTTP लाइब्रेरी (curl, fetch, axios, आदि)

## अगले कदम

- [Memory API](/docs/api/memory) — सबसे महत्वपूर्ण एंडपॉइंट्स
- [Chat API](/docs/api/chat) — अतुल्यकालिक मानव-एजेंट संचार
- [त्रुटियाँ और त्रुटि प्रबंधन](/docs/api/errors)