GiiS REST API Reference

Build AI-powered apps with our battle-tested REST API. All endpoints return JSON. Integrate lead scoring, AI chat, email campaigns, and more into your workflow.

Base URL

https://chat.giis.ai/api

API Status: All endpoints are production-ready and tested against millions of requests. Response times: 95th percentile under 500ms. Rate limits: 60 requests per minute per user.

---

Authentication

All API requests require a valid API key. Authenticate using Bearer token in the Authorization header.

How to get your API key: Sign in to your GiiS account, navigate to Settings → Accounts & Access → API Keys, and create a new API key. Store it securely — treat it like a password.

Request Header

Authorization: Bearer YOUR_API_KEY

GET /auth/verify

Verify your API key is valid.

Response

{
  "valid": true,
  "user_id": "usr_abc123",
  "plan": "pro",
  "rate_limit": 60,
  "requests_used": 12
}

---

Chat API

Send and manage chat messages. Stream responses for real-time interaction. All messages are grounded in your connected knowledge base.

POST /chat/send-message

Stream a message to a chat session. Response streams JSON messages (one per line) until completion.

Request Body

{
  "session_id": "sess_xyz789",
  "message": "What is our Q4 strategy?",
  "model": "claude-3.5-sonnet",
  "temperature": 0.7
}

Parameter	Type	Description
session_id	string	Chat session ID (required)
message	string	User message (required)
model	string	LLM to use: claude-3.5-sonnet, gpt-4o, gemini-1.5-pro (default: claude-3.5-sonnet)
temperature	number	0.0–1.0, higher = more creative (default: 0.7)

Streaming Response

{"type":"chunk","content":"Our Q4 strategy"}
{"type":"chunk","content":" focuses on three"}
{"type":"chunk","content":" key pillars"}
{"type":"done","message_id":"msg_abc123","citations":[{"doc_id":"doc_001","title":"Q4 Plan","page":3}]}

GET /chat/session

List all chat sessions for your account.

Response

{
  "sessions": [
    {
      "session_id": "sess_xyz789",
      "title": "Q4 Planning",
      "created_at": "2026-06-20T14:32:00Z",
      "last_message_at": "2026-06-23T09:15:00Z",
      "message_count": 12
    }
  ],
  "total": 1
}

POST /chat/session

Create a new chat session.

Request Body

{
  "title": "Product Q4 Strategy"
}

Response

{
  "session_id": "sess_new123",
  "title": "Product Q4 Strategy",
  "created_at": "2026-06-23T10:00:00Z"
}

DELETE /chat/session/{session_id}

Delete a chat session permanently.

Response

{
  "status": "deleted",
  "session_id": "sess_xyz789"
}

---

Lead Scraper API

Find business leads with AI-powered search and web scraping. Extract contact information, verify email addresses, and enrich lead data automatically.

POST /tools/lead-scraper

Find and enrich business leads using keyword search or URL scraping.

Request Body

{
  "mode": "keyword_search",
  "query": "VP of Sales at Series B SaaS",
  "max_results": 25,
  "enrichment": ["email", "phone", "socials"]
}

Parameter	Type	Description
mode	string	keyword_search or scrape_url (required)
query	string	Search term or URL (required)
max_results	number	1–50, default 25
enrichment	array	Fields to enrich: email, phone, socials, company_info

Response

{
  "leads": [
    {
      "id": "lead_123",
      "name": "Sarah Johnson",
      "title": "VP of Sales",
      "company": "TechVenture Inc",
      "email": "sarah@techventure.io",
      "phone": "+1-650-555-0123",
      "website": "techventure.io",
      "socials": {
        "linkedin": "linkedin.com/in/sarahjohnson",
        "twitter": "@sarahvpsales"
      },
      "confidence_score": 0.95
    }
  ],
  "total_results": 47,
  "processing_time_ms": 3200
}

---

Email Accounts API

Manage custom SMTP accounts for outreach campaigns. Add, verify, and rotate email sender accounts. Requires Personal plan or higher.

GET /email-accounts

List all personal email accounts connected to your workspace.

Response

{
  "accounts": [
    {
      "id": "email_123",
      "email": "campaigns@acme.io",
      "verified": true,
      "default": true,
      "created_at": "2026-06-10T08:30:00Z",
      "daily_limit": 500,
      "daily_sent": 145
    }
  ],
  "total": 1
}

POST /email-accounts

Add a new custom SMTP account. Requires verification before use.

Request Body

{
  "email": "outreach@company.com",
  "smtp_host": "smtp.gmail.com",
  "smtp_port": 587,
  "smtp_user": "outreach@company.com",
  "smtp_password": "app_password_here",
  "from_name": "Sales Team"
}

Response

{
  "id": "email_new456",
  "email": "outreach@company.com",
  "verified": false,
  "created_at": "2026-06-23T10:05:00Z",
  "verification_token": "verify_abc123xyz"
}

POST /email-accounts/{id}/verify

Send a test email to verify SMTP credentials and deliverability.

Request Body

{
  "test_recipient": "verify@example.com"
}

Response

{
  "verified": true,
  "message": "Test email sent successfully. Account is ready to use."
}

POST /email-accounts/{id}/set-default

Set this account as the default sender for all outreach campaigns.

Response

{
  "id": "email_123",
  "email": "campaigns@acme.io",
  "default": true
}

DELETE /email-accounts/{id}

Remove an email account from your workspace.

Response

{
  "status": "deleted",
  "email": "campaigns@acme.io"
}

---

Gamification API

Track user engagement, streaks, and Horde Points. Record actions and unlock achievements.

GET /gamification/status

Get current user's gamification status including streak, points, and achievements.

Response

{
  "user_id": "usr_abc123",
  "horde_points": 2450,
  "current_streak": 12,
  "longest_streak": 34,
  "achievements_unlocked": ["first_message", "week_warrior", "search_master"],
  "next_milestone": "day_30",
  "progress_to_next": 0.65
}

POST /gamification/action

Record a user action and earn Horde Points.

Request Body

{
  "action_type": "search",
  "context": {
    "query": "Q4 budget",
    "documents_found": 3
  }
}

Response

{
  "action_recorded": true,
  "horde_points_awarded": 15,
  "horde_points_total": 2465,
  "streak_count": 13,
  "is_lucky_find": false,
  "achievement_unlocked": null
}

Points by Action

Action Type	Points Awarded	Streak Impact
login	5	+1
search	10	+1
message	20	+1
share	25	+2
scrape	50	+3
outreach	75	+5

---

Subscription API

Check subscription status, plan tier, and billing information.

GET /subscription/status

Get current subscription plan and billing details.

Response

{
  "plan_tier": "pro",
  "status": "active",
  "renewal_date": "2026-07-23T23:59:59Z",
  "amount_monthly": 5900,
  "currency": "USD",
  "trial_active": false,
  "features": {
    "users": 10,
    "storage_gb": 500,
    "email_accounts": 5,
    "custom_domain": true,
    "api_access": true
  }
}

Plans

Plan	Price/mo	Users	API Access
Free	$0	1	✓
Personal	$29	3	✓
Pro	$59	10	✓
Agency	$149	50	✓
Enterprise	Custom	Unlimited	✓

---

Webhooks

Receive real-time notifications for subscription and user events.

Configure webhooks: Go to Settings → Integrations → Webhooks to add your endpoint URL. All webhook payloads are signed with an HMAC-SHA256 signature in the X-Signature header.

checkout.session.completed

Fires when a user completes a Stripe checkout.

Payload

{
  "id": "evt_stripe_123",
  "type": "checkout.session.completed",
  "timestamp": "2026-06-23T10:15:00Z",
  "data": {
    "session_id": "cs_test_abc123",
    "customer_email": "user@example.com",
    "plan_tier": "pro",
    "amount_total": 5900,
    "currency": "USD"
  }
}

customer.subscription.deleted

Fires when a subscription is cancelled.

Payload

{
  "id": "evt_stripe_456",
  "type": "customer.subscription.deleted",
  "timestamp": "2026-06-23T11:30:00Z",
  "data": {
    "subscription_id": "sub_test_xyz789",
    "customer_email": "user@example.com",
    "cancellation_reason": "user_requested",
    "effective_date": "2026-06-23T11:30:00Z"
  }
}

---

Error Handling

All API errors follow a consistent JSON format. Use the error_code field to handle failures programmatically.

Error Response Format

{
  "error_code": "NOT_FOUND",
  "detail": "Session not found",
  "request_id": "req_abc123xyz"
}

Error Code	HTTP Status	Description
UNAUTHENTICATED	401	Missing, invalid, or expired API key
UNAUTHORIZED	403	API key lacks permission for this resource
NOT_FOUND	404	Resource does not exist
BAD_REQUEST	400	Invalid request parameters or malformed JSON
RATE_LIMIT_EXCEEDED	429	Exceeded rate limit (60 requests/minute)
BAD_GATEWAY	502	Upstream service error
INTERNAL_SERVER_ERROR	500	Unexpected server error. Contact support if persistent.

---

Rate Limits

All API requests are rate limited per user account.

60 requests per minute per API key. When you exceed the limit, the API returns a 429 Too Many Requests response with a Retry-After header.

429 Rate Limit Response

HTTP/1.1 429 Too Many Requests
Retry-After: 45
Content-Type: application/json

{
  "error_code": "RATE_LIMIT_EXCEEDED",
  "detail": "Rate limit of 60 requests/min exceeded. Retry after 45 seconds."
}

Best Practices

• Implement exponential backoff when you hit a rate limit. Start with 1 second, double on each retry.
• Batch requests where possible. Use bulk endpoints to process multiple items in a single call.
• Cache responses. If you need the same data multiple times, store it locally for 5–10 minutes.
• Upgrade your plan if you consistently hit rate limits. Higher tiers get higher limits.

---

SDKs

Official SDKs for popular languages are in development. Use the REST API directly for now.

Python SDK (coming soon)

Type-safe SDK with async support, automatic retries, and streaming response handling.

pip install giis-sdk

Node.js SDK (coming soon)

TypeScript SDK with full ESM/CommonJS support, built-in streaming, and response validation.

npm install @giis/sdk

In the meantime: All examples in this documentation use REST with cURL. Use axios (Node.js), requests (Python), fetch (JavaScript), or urllib to call the API endpoints directly.