Sessions API

Organize multi-step research workflows with automatic URL deduplication, credit tracking, and context inheritance.

Lifecycle: active → completed → archived

Credits: Same as individual operations (search/crawl)

GET /api/v1/sessions

List sessions with pagination and filtering.

Query Parameters:

• limit (Int) - Results per page (1-100)
• offset (Int) - Pagination offset
• status (String) - Filter by status
• tag (String) - Filter by tag
• days_back (Int) - Filter by recency
• include_shared (Bool) - Include org-shared sessions from teammates

Response with include_shared=true:

{
  "sessions": [...],
  "shared_sessions": [...],
  "user_organizations": [{"id": "...", "name": "..."}],
  "pagination": {
    "owned": {"total": 10, "limit": 10, "offset": 0},
    "shared": {"total": 5, "limit": 10, "offset": 0}
  }
}

POST /api/v1/sessions

Create a new session.

Limits: 100 sessions/user, 1-100 operations/session, auto-archive after 7 days

GET /api/v1/sessions/{id}

Get session details including operations, context_summary, and access level.

Response includes:

• access_level - Your access level: owner, org_viewer, or public
• organization_name - Organization name if shared with an org
• user_organizations - Your organizations (for sharing UI)

PATCH /api/v1/sessions/{id}

Update session properties: name, description, intent_context, config.

DELETE /api/v1/sessions/{id}

Delete session and all associated operations (permanent).

POST /api/v1/sessions/{id}/complete

Mark session as completed. Prevents new operations from being added.

POST /api/v1/sessions/{id}/archive

Archive a completed session. Session must be completed first.

POST /api/v1/sessions/{id}/share

Toggle public or organization sharing for a session.

Body Parameters:

Cascade Behavior: When org sharing is changed, all child operations (search jobs and crawls) in the session are automatically updated to match.

Example:

# Share with organization
curl -X POST https://www.zipf.ai/api/v1/sessions/SESSION_ID/share \
  -H "Authorization: Bearer wvr_TOKEN" \
  -d '{"shared_with_org": true, "organization_id": "ORG_ID"}'

# Response includes operations updated
{
  "session": {...},
  "operations_updated": {
    "org_share": {"searches": 3, "crawls": 2}
  }
}

GET /api/v1/sessions/{id}/timeline

Get chronological timeline of all session operations with status, results, and credits.

GET /api/v1/sessions/{id}/export

Export session data.

Query Parameters:

• format (String) - Export format: json or csv

GET /api/v1/sessions/{id}/link-graph

Get aggregated link graph across all crawls in a session. Includes cumulative PageRank, domain authority, and HITS analysis. Cost: FREE

Query Parameters:

Response:

{
  "session_id": "uuid",
  "link_graph": {
    "stats": {
      "total_nodes": 500,
      "total_edges": 1200,
      "operations_included": 3,
      "total_pages_crawled": 45
    },
    "domain_authority": {"example.com": 0.85},
    "hubs": [{"url": "...", "score": 0.18}],
    "authorities": [{"url": "...", "score": 0.25}],
    "nodes": [{"url": "...", "pagerank": 0.05, "inlinks": 10}],
    "last_updated": "2026-01-27T12:00:00Z"
  }
}

See Crawl API - Link Graph for detailed documentation.

POST /api/v1/sessions/{id}/search

Search within a session context. Same parameters as POST /api/v1/search plus:

• filter_seen_urls (Bool, default: false) - Exclude URLs already in session

POST /api/v1/sessions/{id}/crawl

Crawl within a session context. Same parameters as POST /api/v1/crawls plus:

• filter_seen_urls (Bool, default: true) - Exclude URLs already in session

GET /api/v1/public/sessions/{id}

View a publicly shared session (no authentication required).

GET /api/v1/public/sessions/{id}/timeline

View public session timeline (no authentication required).

GET /api/v1/public/sessions/{id}/export

Export public session data (no authentication required).

Organization Sharing

Share sessions with your organization's team members for collaborative research workflows.

Access Levels

Cascade Behavior

When you share a session with your organization:

1. All child operations (search jobs and crawls) are automatically shared
2. Child operations inherit the session's organization and sharing status
3. Removing org sharing from a session removes it from all children

Workflow Integration

Workflows with linked sessions cascade org sharing:

• Sharing a workflow shares its linked session
• Session cascade then shares all child operations
• Consistent access across the entire workflow pipeline

Session Context for AI Features

When use_session_context: true, AI features receive accumulated context:

Intent Types & Effects

Reranking Boosts

• Authority Alignment (1.25x): Based on authority_preference (academic/news/technical)
• Document Type (1.15x): Matching dominant_document_types
• Novelty Scoring: novelty = exp(-0.15 × domain_count)

URL Deduplication vs Novelty Reranking

Example

# Create session
curl -X POST https://www.zipf.ai/api/v1/sessions \
  -H "Authorization: Bearer wvr_TOKEN" \
  -d '{"name": "AI Research", "intent_context": "Competitive analysis", "session_config": {"auto_deduplicate": true}}'

# Search in session
curl -X POST https://www.zipf.ai/api/v1/sessions/SESSION_ID/search \
  -H "Authorization: Bearer wvr_TOKEN" \
  -d '{"query": "AI startups", "filter_seen_urls": true}'

# Share with organization (cascades to all operations)
curl -X POST https://www.zipf.ai/api/v1/sessions/SESSION_ID/share \
  -H "Authorization: Bearer wvr_TOKEN" \
  -d '{"shared_with_org": true, "organization_id": "ORG_ID"}'

# List including shared sessions
curl https://www.zipf.ai/api/v1/sessions?include_shared=true \
  -H "Authorization: Bearer wvr_TOKEN"

See Also

• Search API | Crawl API | Common Topics