Semantik Python SDK

Python SDK for the Semantik Client API. Designed for Python 3.8+ applications.

Installation

pip install semantik-sdk
# or with uv:
uv pip install semantik-sdk

Quick Start

from semantik import Semantik
import base64

# Automatically reads from SEMANTIK_API_KEY environment variable (recommended)
# Set SEMANTIK_API_KEY in your .env file or environment
client = Semantik()

# Or override with explicit API key
client = Semantik(api_key="sk_your_api_key_here")

# List programs
programs_response = client.programs.list()
print(f"Found {len(programs_response['programs'])} programs")

# Get a specific program
program = client.programs.get(programs_response['programs'][0]['id'])

# Submit a candidate application
with open('resume.pdf', 'rb') as f:
    cv_content = base64.b64encode(f.read()).decode('utf-8')

result = client.candidates.submit_application(
    candidate={
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com"
    },
    program_id=program['id'],
    step_id=program['steps'][0]['id'],
    documents=[
        {
            "fieldName": "CV",
            "content": cv_content,
            "fileName": "john-doe-cv.pdf",
            "mimeType": "application/pdf",
            "encoding": "base64"
        }
    ]
)

print(f"Application submitted: {result['applicationId']}")
print(f"Candidate ID: {result['candidateId']}")

# Get candidate status
status = client.candidates.get_status(result['candidateId'], include="applications,scores")
print(f"Candidate: {status['candidate']['firstName']} {status['candidate']['lastName']}")

# Move candidate to next step
move_result = client.programs.move_candidate(
    program_id=program['id'],
    candidate_id=result['candidateId'],
    direction="next"
)
print(f"Moved from {move_result['movement']['from']['name']} to {move_result['movement']['to']['name']}")

Configuration

API Key

Set your API key as an environment variable (recommended):

export SEMANTIK_API_KEY=sk_your_api_key_here

Or pass it directly to the client:

client = Semantik(api_key="sk_your_api_key_here")

Base URL

The SDK defaults to production (https://gateway.semantikmatch.com). For local development:

client = Semantik(
    api_key="sk_...",
    base_url="http://localhost:9000"
)

Or set SEMANTIK_BASE_URL environment variable.

API Reference

Programs

• client.programs.list() - List all programs
• client.programs.get(program_id) - Get a specific program
• client.programs.list_candidates(program_id, step_id=None, status=None, search=None, include=None, limit=None, cursor=None) - List candidates in a program
• client.programs.move_candidate(program_id, candidate_id, direction="next"|"previous", from_step_id=None, to_step_id=None) - Move a candidate between steps

Candidates

• client.candidates.submit_application(candidate, program_id, step_id, client_data=None, documents=None) - Submit a new application
• client.candidates.get_status(candidate_id, include=None) - Get candidate status across all programs
• client.candidates.get_applications(candidate_id, include=None) - Get all applications for a candidate
• client.candidates.get_scores(candidate_id, include=None) - Get candidate scores
• client.candidates.enroll(candidate_id, program_id, step_id=None, send_email=None, email_template=None) - Enroll candidate in a program

Error Handling

from semantik import Semantik, ApiError

try:
    program = client.programs.get(999)
except ApiError as e:
    print(f"API Error {e.status}: {e}")
    print(f"Path: {e.path}")
    print(f"Response: {e.response}")
except Exception as e:
    print(f"Unexpected error: {e}")

Type Hints

The SDK includes full type hints for better IDE support and type checking.

Support

For issues or questions, please contact support or visit the documentation.