Skip to content

REST API

Use Jobko with any HTTP client.

Base URL

https://jobko.ai/api/mcp

Authentication

Include your API key in the Authorization header:

Authorization: Bearer jk_YOUR_KEY

Endpoints

List Tools

GET /tools

Returns available tools based on your API key scopes.

curl https://jobko.ai/api/mcp/tools \
  -H "Authorization: Bearer jk_YOUR_KEY"

{
  "tools": [
    {
      "name": "get_profile",
      "description": "Get user profile",
      "inputSchema": {}
    },
    {
      "name": "analyze_job",
      "description": "Analyze a job posting",
      "inputSchema": {
        "type": "object",
        "properties": {
          "job_url": {"type": "string"}
        }
      }
    }
  ]
}

Call a Tool

POST /tools/call
Content-Type: application/json

{
  "name": "tool_name",
  "arguments": {}
}

curl -X POST https://jobko.ai/api/mcp/tools/call \
  -H "Authorization: Bearer jk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "get_profile", "arguments": {}}'

{
  "content": [
    {
      "type": "text",
      "text": "{\"name\": \"John Doe\", \"skills\": {...}}"
    }
  ],
  "isError": false
}

Check Status

GET /status

Returns credit balance and API key info.

curl https://jobko.ai/api/mcp/status \
  -H "Authorization: Bearer jk_YOUR_KEY"

{
  "credits": {
    "balance_dollars": "5.00",
    "balance_cents": 500
  },
  "api_key": {
    "name": "My Agent",
    "scopes": ["profile_read", "job_analysis"],
    "rate_limit_per_hour": 100
  }
}

Server Info

GET /info

Returns server metadata (no authentication required).

{
  "name": "jobko-mcp",
  "version": "1.0.0",
  "capabilities": {
    "tools": true,
    "resources": false,
    "prompts": false
  }
}

MCP Protocol (JSON-RPC)

For MCP-native clients, use JSON-RPC 2.0:

POST /
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_profile",
    "arguments": {}
  }
}

Code Examples

Python

import requests

API_KEY = "jk_YOUR_KEY"
BASE_URL = "https://jobko.ai/api/mcp"

def call_tool(name: str, arguments: dict = None):
    response = requests.post(
        f"{BASE_URL}/tools/call",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"name": name, "arguments": arguments or {}}
    )
    response.raise_for_status()
    return response.json()

# Analyze a job
result = call_tool("analyze_job", {"job_url": "https://linkedin.com/jobs/view/123"})
print(result)

JavaScript

const API_KEY = "jk_YOUR_KEY";
const BASE_URL = "https://jobko.ai/api/mcp";

async function callTool(name, args = {}) {
  const response = await fetch(`${BASE_URL}/tools/call`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ name, arguments: args })
  });
  return response.json();
}

// Analyze a job
const result = await callTool("analyze_job", { job_url: "https://linkedin.com/jobs/view/123" });
console.log(result);

Go

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func callTool(name string, args map[string]interface{}) (map[string]interface{}, error) {
    body, _ := json.Marshal(map[string]interface{}{
        "name":      name,
        "arguments": args,
    })

    req, _ := http.NewRequest("POST", "https://jobko.ai/api/mcp/tools/call", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer jk_YOUR_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    return result, nil
}

HTTP Status Codes

Code Meaning
200 Success
400 Bad request
401 Invalid API key
402 Insufficient credits
403 Scope not allowed
429 Rate limit exceeded
500 Server error