Use the Jules REST API (v1alpha) via curl to list sources, create sessions, monitor activities, approve plans, send messages, and retrieve outputs (e.g., PR URLs). Use when the user wants to delegate coding tasks to Jules programmatically.
Use the Jules REST API (v1alpha) via curl to list sources, create sessions, monitor activities, approve plans, send messages, and retrieve outputs (e.g., PR URLs). Use when the user wants to delegate coding tasks to Jules programmatically.
Jules REST API Skill
Quick Start
# 1. Verify available sources (pre-flight check)
./scripts/jules_api.sh sources
# 2. Create a session with auto PR creation
./scripts/jules_api.sh new-session \
--source"sources/github/OWNER/REPO" \
--title "Add unit tests" \
--prompt "Add comprehensive unit tests for the authentication module" \
--branch main \
--auto-pr
# 3. Monitor session progress
./scripts/jules_api.sh activities --session SESSION_ID
Note: Use your GitHub username/org, not your local system username (e.g., sources/github/octocat/Hello-World, not sources/github/$USER/Hello-World).
Overview
This skill enables programmatic interaction with the Jules REST API (v1alpha) for delegating coding tasks to Jules, Google's autonomous AI coding agent. It supports:
Task Assignment: Create new coding sessions with specific prompts
Session Monitoring: Track session state and activities in real-time
Plan Management: Approve or review generated plans
Messaging: Send follow-up messages to active sessions
Result Integration: Retrieve PR URLs and code changes from completed sessions
A GitHub repository connected to Jules. Format: sources/github/{owner}/{repo}
Session
A unit of work where Jules executes a coding task. Contains state, activities, and outputs
Activity
An individual event within a session (plan generated, message sent, progress update, etc.)
Session States
State
Description
QUEUED
Session is waiting to start
PLANNING
Generating execution plan
AWAITING_PLAN_APPROVAL
Waiting for user to approve plan
AWAITING_USER_FEEDBACK
Needs user input to continue
IN_PROGRESS
Actively executing the task
PAUSED
Temporarily stopped
COMPLETED
Successfully finished
FAILED
Encountered an error
Activity Types
Type
Description
Plan Generated
A plan was generated for the task
Plan Approved
The plan was approved (manually or auto)
User Message
User posted a message to the session
Agent Message
Jules posted a message
Progress Update
Status update on current work
Session Completed
Session finished successfully
Session Failed
Session encountered an error
Workflows
Option 1: Automated Session with Auto-PR (Recommended)
Create a session that automatically creates a PR when complete:
./scripts/jules_api.sh new-session \
--source"sources/github/octocat/Hello-World" \
--title "Fix login bug" \
--prompt "Fix the null pointer exception in the login handler when email is empty" \
--branch main \
--auto-pr
Why this is recommended:
Plans are automatically approved (default behavior)
PR is created automatically on completion
Minimal manual intervention required
Option 2: Session with Plan Approval
For sensitive operations, require explicit plan approval:
# Create session requiring plan approval
./scripts/jules_api.sh new-session \
--source"sources/github/octocat/Hello-World" \
--title "Refactor auth module" \
--prompt "Refactor the authentication module to use OAuth2" \
--branch main \
--require-plan-approval \
--auto-pr
# Monitor until AWAITING_PLAN_APPROVAL state
./scripts/jules_api.sh activities --session SESSION_ID
# Review the plan, then approve
./scripts/jules_api.sh approve-plan --session SESSION_ID
Option 3: Interactive Session
Send follow-up messages during an active session:
# Create session
./scripts/jules_api.sh new-session \
--source"sources/github/octocat/Hello-World" \
--title "Add API endpoints" \
--prompt "Add REST API endpoints for user management" \
--branch main
# Send additional instructions
./scripts/jules_api.sh send-message \
--session SESSION_ID \
--prompt "Also add input validation for all endpoints"
{"name":"sessions/31415926535897932384","id":"31415926535897932384","prompt":"Add unit tests for the login module","title":"Add Login Tests","state":"QUEUED","url":"https://jules.google/session/31415926535897932384","createTime":"2026-01-15T10:30:00Z","updateTime":"2026-01-15T10:30:00Z"}
{"activities":[{"name":"sessions/123/activities/456","createTime":"2026-01-15T10:31:00Z","planGenerated":{"plan":"1. Analyze existing code\n2. Create test files\n3. Write tests..."}},{"name":"sessions/123/activities/457","createTime":"2026-01-15T10:32:00Z","progressUpdate":{"title":"Writing tests","details":"Creating test file for auth module..."}}],"nextPageToken":"..."}
Activities may include artifacts with code changes:
{"artifacts":[{"changeSet":{"gitPatch":{"unidiffPatch":"diff --git a/...","baseCommitId":"abc123","suggestedCommitMessage":"Add unit tests for login"}}}]}
