Screen API usage

The Screen API is available on the same client via screen_api_key.

"""Screen API usage example."""

import sys

from coderpad.client import CoderPad
from coderpad.screen_types import ScreenInvitation

client = CoderPad(
    api_key="your-interview-api-key",
    screen_api_key="your-screen-api-key",
)
campaigns = client.screen.campaigns.list()
_ = sys.stdout.write(campaigns[0].name)
invitation = ScreenInvitation(
    candidate_email="candidate@example.com",
    candidate_name="Ada Lovelace",
)
result = client.screen.campaigns.send_invitation(
    campaign_id=campaigns[0].id,
    invitation=invitation,
)
if result.test_url is not None:
    _ = sys.stdout.write(result.test_url)

Manual invitations

Omit candidate identity to create a test link that you can share yourself. Pass send_invitation_email=False to explicitly disable email delivery. A candidate name is optional for both manual and email invitations. Explicit email delivery requires a candidate email address. When delivery is omitted, the server sends email only if an address is provided. Set allow_duplicate_invitations=False on ScreenInvitation to ask the server to reject repeated invitations. Omission uses the server default, which allows duplicates. Explicit True allows them.

Account introspection

Use client.user.get() to inspect the Interview key owner. Its fields are name, allow_pad_creation, and analytics_id. Use client.screen.me() to inspect the Screen key owner, including organization_id, recruiter_id, and teams. Each call uses the key for its product. The asynchronous client exposes the same methods.

Campaign definitions

Use client.screen.campaigns.get(campaign_id=121) to retrieve a ScreenCampaignDetails. It contains ordered explicit questions and random question sets, settings, and the team ID. Optional settings preserve omitted, false, and empty values, and read models ignore additive server fields. These definitions differ from candidate sessions returned by screen.tests. Both synchronous and asynchronous clients support the operation.

Creating campaigns

Use screen.campaigns.create with a name and an ordered list of ScreenCampaignQuestion or ScreenRandomQuestionSet entries. Question IDs and team IDs are UUID strings. The response is ScreenCreatedCampaign, containing the integer campaign ID.

ScreenRandomQuestionConfiguration selects domain, skills, question type, duration, and experience level. Its included and excluded question ID lists are mutually exclusive.

ScreenCampaignSettings supports locales, timers, invitation expiration, access windows, follow-up questions, webcam recording, full screen, copy and paste restrictions, simplified reports, AI Assist, and coding agents. enabled_coding_agents is sent as a string. An empty string disables agents. Omitted settings inherit team defaults. Explicit false values are retained. The service reports account feature restrictions and incompatible settings. Campaign creation is never automatically retried.

AI Assist conversations

client.screen.tests.ai_assist_conversations(test_id=11, question_id=question_uuid) returns ordered ScreenAIConversation values and ordered ScreenAIMessage values for a PROJECT question. The question ID accepts a UUID or a UUID string. Conversations become available after completion or while awaiting manual review. The normal API error contract applies to missing project questions (404) and unfinished sessions (409).

Message roles retain USER or ASSISTANT. ISO 8601 creation timestamps are preserved as returned strings. output_items retains structured JSON, including unknown nested fields, text chunks, reasoning, and tool-call metadata. It is None when omitted and an empty list when explicitly empty. No output is collapsed into plain text. Both synchronous and asynchronous clients support this operation.

Candidate project archives

client.screen.tests.project_archive(test_id=11, question_id=question_uuid) returns the project tar.gz bytes with the candidate’s changes applied. The question ID accepts a UUID or a UUID string. Your application decides whether to save or extract the bytes, which the SDK returns without interpreting them as JSON or PDF or retrying requests. HTTP errors use the public CoderPadError contract, and transport errors propagate as they do for PDF downloads. For slow project generation, configure the client’s timeout or supply a Screen transport with an appropriate timeout. The asynchronous client provides the same operation and supports normal task cancellation.

Question insights

client.screen.questions.insights(question_id=question_uuid) returns a typed ScreenQuestionInsights response. Use programming_language to request language-specific statistics. The question identity accepts a UUID or a UUID string. Usage includes view count, last view timestamp, average duration in seconds, timeout ratio, and average score ratio. Frequent answers and test-case success retain labeled counts and ratios, while score distribution retains zero, partial, and full score buckets and total candidates. Absent statistics remain None and explicitly empty lists remain empty. API errors use the usual error contract, including 400 and 404 responses. Both synchronous and asynchronous clients provide the same operation.

Detailed test results

client.screen.tests.get(test_id=11) returns a ScreenTest with optional session timer_type, organization, candidate language, and approval status. Its questions contains ScreenDetailedQuestion objects with string UUID IDs when the server returns detailed reports. tests.list continues to decode integer IDs as ScreenTestQuestion summaries. When report permissions hide the questions, the list is empty.

Detailed questions retain version, type, title, domain, scores, answer and grading status, timestamps in milliseconds, and elapsed time in seconds. A missing value stays None. Explicit zero, false, and empty lists remain distinct. The server returns question time limits only for PER_QUESTION timers. Question warnings retain an open type identifier, level, and message. Session warnings remain the existing string list on ScreenReport. Report and question activity fields distinguish recruiter cheating flags from platform warnings.

question.answer exposes typed code, game, text, MCQ, file, project, and video blocks. question.evaluation exposes rubric and AI reviews, project tests, validation methods, output comparisons, SQL comparisons, accepted text answers, and correct choice indexes. Order is preserved for choices, recordings, criteria, and test cases. Recorded outcomes and points already include recruiter overrides. Optional blocks stay absent until available, including pending reviews and unavailable recordings. File, video, and transcript URLs are temporary. Project archive downloads require the independent Screen key. No answer content or media is downloaded automatically. The same models are returned by synchronous and asynchronous clients.

Question library reads and writes

client.screen.questions.list returns a ScreenQuestionsPage of ScreenQuestionSummary values and offset pagination metadata. Use ScreenQuestionFilters for type, minimum and maximum duration, difficulty, domain, skill, programming language, question-bank origin, product, sort field, and order. For example, ScreenQuestionFilters(programming_language="C++", from_coderpad_question_bank=False, order="desc") keeps false values explicit. start and limit are separate page arguments. client.screen.questions.all(filters=filters, limit=50) preserves those filters on every page and rejects offsets that do not advance.

client.screen.questions.get(question_id=question_uuid) accepts a UUID or UUID string and returns ScreenQuestionDetails. Summary titles and detail statements retain their locale maps. Details expose type-specific content and evaluation settings, including project environments, additional resources, source archive URLs, and version metadata. Read models include legacy GAME, MULTI, CLASH, and COURSE kinds as well as CODE, MCQ, TEXT, FILE_UPLOAD, PROJECT, and VIDEO. Unknown response properties are ignored for compatibility with additive API changes.

Create or update using ScreenQuestionSave with a writable type and explicit fields. Response identifiers, versions, timestamps, and other server-owned fields are rejected by save models, including nested available-language lists, project download URLs, and project test-report configuration. Use ScreenCodeInput, ScreenProjectInput, and the other input models for writable content and evaluation settings. Omitted or None fields stay absent, while false, zero, and empty lists are retained. The service validates locale coverage, question-type rules, permissions, and account capabilities.

client.screen.questions.create(question=payload) returns ScreenCreatedQuestion with question details and the optional location response header. client.screen.questions.update(question_id=question_uuid, question=payload) uses PUT and returns updated details. Project creation accepts the upload ID through ScreenProjectInput(temporary_file_id=upload_id). The service accepts this archive reference only for creation. Updating a project archive requires the question editor. Creation and updates make one request and never automatically retry. API errors retain the normal public error contract, including validation, permission, missing-question, and conflict responses. The asynchronous client provides the same operations, and its all method is an asynchronous iterator.

Temporary project uploads

client.screen.temporary_files.upload(content=archive_bytes) rejects bodies larger than 52,428,800 bytes before networking and sends accepted bytes as application/gzip with the exact Content-Length. The returned ScreenTemporaryFile.id should be used promptly as project_details.temporary_file_id when saving a Screen project question. Unused uploads are eventually deleted by the service. Upload permission errors use the normal API error contract, and writes are never retried automatically. Both synchronous and asynchronous default transports support raw bodies. Custom Screen transports need the content keyword for uploads. Existing JSON-only operations continue to accept JSON-only custom transports.