Internal REST API

Istek includes a built-in REST API that enables external integrations, automation, and AI assistant connectivity.

Overview

When Istek starts, it automatically launches an internal REST API server on port 47835. This API provides programmatic access to:

• Workspaces
• Collections and Requests
• Environments and Variables
• Request History
• Secret Provider Integrations

API Base URL

http://localhost:47835/api

Documentation

Swagger UI

Interactive API documentation is available at:

http://localhost:47835/api/docs

OpenAPI Specification

The OpenAPI 3.0 spec is available at:

http://localhost:47835/api/openapi.json

Authentication

The API is designed for local use only and does not require authentication. It only accepts connections from localhost.

Endpoints

Health Check

GET /api/health

Returns API status and version.

Response:

{
  "status": "ok",
  "version": "0.1.0"
}

Workspaces

Method	Endpoint	Description
GET	/api/workspaces	List all workspaces
POST	/api/workspaces	Create a workspace
GET	/api/workspaces/:id	Get a workspace
PUT	/api/workspaces/:id	Update a workspace
DELETE	/api/workspaces/:id	Delete a workspace
PUT	/api/workspaces/:id/activate	Set as active workspace

Collections

Method	Endpoint	Description
GET	/api/workspaces/:wid/collections	List collections
POST	/api/workspaces/:wid/collections	Create a collection
GET	/api/workspaces/:wid/collections/:id	Get a collection
PUT	/api/workspaces/:wid/collections/:id	Update a collection
DELETE	/api/workspaces/:wid/collections/:id	Delete a collection
POST	/api/workspaces/:wid/collections/:id/requests	Add a request
PUT	/api/workspaces/:wid/collections/:id/requests/:rid	Update a request
DELETE	/api/workspaces/:wid/collections/:id/requests/:rid	Delete a request

Environments

Method	Endpoint	Description
GET	/api/workspaces/:wid/environments	List environments
POST	/api/workspaces/:wid/environments	Create an environment
GET	/api/workspaces/:wid/environments/:id	Get an environment
PUT	/api/workspaces/:wid/environments/:id	Update an environment
DELETE	/api/workspaces/:wid/environments/:id	Delete an environment
PUT	/api/workspaces/:wid/environments/:id/activate	Activate environment

Global Variables

Method	Endpoint	Description
GET	/api/workspaces/:wid/variables	List global variables
POST	/api/workspaces/:wid/variables	Create a variable
PUT	/api/workspaces/:wid/variables/:id	Update a variable
DELETE	/api/workspaces/:wid/variables/:id	Delete a variable

History

Method	Endpoint	Description
GET	/api/workspaces/:wid/history	List history items
GET	/api/workspaces/:wid/history/:id	Get a history item
DELETE	/api/workspaces/:wid/history/:id	Delete a history item
DELETE	/api/workspaces/:wid/history	Clear all history

Pagination

List endpoints support pagination:

GET /api/workspaces?limit=50&offset=0

Response:

{
  "items": [...],
  "total": 100,
  "limit": 50,
  "offset": 0
}

Error Handling

Errors return appropriate HTTP status codes with a JSON body:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Workspace not found"
  }
}

Status	Code	Description
400	BAD_REQUEST	Invalid request data
404	NOT_FOUND	Resource not found
500	INTERNAL_ERROR	Server error

MCP Integration

The Istek MCP Server uses this API to enable AI assistants to interact with Istek. See MCP Protocol for details.

Setting Up MCP

Add Istek to your AI assistant's MCP configuration:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "istek": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-istek"]
    }
  }
}

Available MCP Tools

When connected via MCP, AI assistants can:

Tool	Description
list_workspaces	List all workspaces
create_workspace	Create a new workspace
list_collections	List collections in a workspace
create_collection	Create a new collection
add_request_to_collection	Add an API request
list_environments	List environments
create_environment	Create an environment
create_variable	Create a global variable
list_history	View request history
check_istek_status	Check if Istek is running

Available MCP Prompts

Prompt	Description
create_rest_api_collection	Create a complete REST API collection
setup_environment	Set up dev/staging/prod environments
create_crud_collection	Create CRUD endpoints for a resource
import_from_curl	Convert cURL to Istek request
setup_auth_environment	Set up authentication variables
create_graphql_collection	Create GraphQL queries/mutations
create_webhook_collection	Create webhook test collection
api_testing_guide	Get a guided API testing workflow

Example Usage

cURL

# List workspaces
curl http://localhost:47835/api/workspaces

# Create a collection
curl -X POST http://localhost:47835/api/workspaces/ws_123/collections \
  -H "Content-Type: application/json" \
  -d '{"name": "My API"}'

# Add a request to collection
curl -X POST http://localhost:47835/api/workspaces/ws_123/collections/col_456/requests \
  -H "Content-Type: application/json" \
  -d '{
    "request": {
      "name": "Get Users",
      "method": "GET",
      "url": "https://api.example.com/users"
    }
  }'

JavaScript

const ISTEK_API = 'http://localhost:47835/api';

// List workspaces
const workspaces = await fetch(`${ISTEK_API}/workspaces`)
  .then(r => r.json());

// Create environment
await fetch(`${ISTEK_API}/workspaces/${workspaceId}/environments`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Production',
    color: '#ef4444',
    variables: [
      { key: 'API_URL', value: 'https://api.prod.example.com', isSecret: false }
    ]
  })
});

Viewing API in Istek

1. Open Istek
2. Go to Settings (gear icon)
3. Click the API tab
4. View API status and quick access to Swagger UI