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

Before You Start

1. Get an API Key

Create a Jules API key in the Jules web app:

• Navigate to:


• You can have at most 3 API keys at a time

Export it on the machine running the agent:

export JULES_API_KEY="your-api-key-here"

2. Connect Your GitHub Repository

Before the API can operate on a GitHub repo, you must:

Install the Jules GitHub app via the Jules web UI

Grant access to the specific repositories you want Jules to work on

3. Verify Repository Access

# List available sources to verify access and see correct format
./scripts/jules_api.sh sources

You'll see entries like:

{
  "sources": [
    {
      "name": "sources/github/octocat/Hello-World",
      "githubRepo": {
        "owner": "octocat",
        "repo": "Hello-World",
        "defaultBranch": { "displayName": "main" },
        "branches": [
          { "displayName": "main" },
          { "displayName": "develop" }
        ]
      }
    }
  ]
}

Base URL & Authentication

Property

Value

| Base URL | | | Auth Header | x-goog-api-key: $JULES_API_KEY | All requests authenticate with: __CODE_BLOCK_4__ ## Core Concepts ### Resources | Resource | Description | |----------|-------------| | **Source** | 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: __CODE_BLOCK_5__ **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: __CODE_BLOCK_6__ ### Option 3: Interactive Session Send follow-up messages during an active session: __CODE_BLOCK_7__ ## API Reference ### Sources #### List Sources Lists all connected GitHub repositories. __CODE_BLOCK_8__ **Query Parameters:** | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | pageSize | integer | 30 | Number of sources to return (1-100) | | pageToken | string | - | Token from previous response for pagination | | filter | string | - | AIP-160 filter (e.g., name=sources/source1) | **Response:** __CODE_BLOCK_9__ #### Get Source Retrieves a single source by name. __CODE_BLOCK_10__ Use this to see available branches before creating a session. --- ### Sessions #### Create Session Creates a new coding session. __CODE_BLOCK_11__ **Request Body Fields:** | Field | Type | Required | Description | |-------|------|----------|-------------| | prompt | string | Yes | The task description for Jules | | title | string | No | Short title for the session | | sourceContext.source | string | Yes | Source name (e.g., sources/github/owner/repo) | | sourceContext.githubRepoContext.startingBranch | string | Yes | Branch to start from | | requirePlanApproval | boolean | No | If true, pause for plan approval (default: false) | | automationMode | string | No | Set to AUTO_CREATE_PR for automatic PR creation | **Response:** __CODE_BLOCK_12__ #### List Sessions Lists your sessions. __CODE_BLOCK_13__ **Query Parameters:** | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | pageSize | integer | 30 | Number of sessions to return (1-100) | | pageToken | string | - | Token from previous response for pagination | #### Get Session Retrieves a single session by ID. __CODE_BLOCK_14__ **Response includes outputs on completion:** __CODE_BLOCK_15__ #### Send Message Sends a message to an active session. __CODE_BLOCK_16__ Use this to provide feedback, answer questions, or give additional instructions. #### Approve Plan Approves a pending plan (only needed if requirePlanApproval was true). __CODE_BLOCK_17__ #### Delete Session Deletes a session. __CODE_BLOCK_18__ --- ### Activities #### List Activities Lists activities for a session. __CODE_BLOCK_19__ **Query Parameters:** | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | pageSize | integer | 50 | Number of activities to return (1-100) | | pageToken | string | - | Token from previous response for pagination | **Response:** __CODE_BLOCK_20__ Activities may include artifacts with code changes: __CODE_BLOCK_21__ #### Get Activity Retrieves a single activity by ID. __CODE_BLOCK_22__ ## Script Reference ### jules_api.sh The scripts/jules_api.sh script provides a convenient wrapper for common API operations. **Usage:** __CODE_BLOCK_23__ **Flags:** | Flag | Description | |------|-------------| | --source | Source name (format: sources/github/owner/repo) | | --title | Session title | | --prompt | Task description or message content | | --session | Session ID | | --branch | Starting branch (default: main) | | --auto-pr | Enable automatic PR creation | | --require-plan-approval | Require explicit plan approval | | --page-size | Number of results to return | ### jules.js The scripts/jules.js script wraps the Jules CLI for programmatic use. **Usage:** __CODE_BLOCK_24__ ## Common Error Patterns ### "Source not found" or "Repository not found" **Cause:** Repository not connected or incorrect source name format. **Solution:** 1. Run ./scripts/jules_api.sh sources to list available sources 2. Ensure you've installed the Jules GitHub app for this repo 3. Use the exact source name from the list (e.g., sources/github/octocat/Hello-World) ### "Missing JULES_API_KEY" **Cause:** API key not set in environment. **Solution:** __CODE_BLOCK_25__ ### Authentication Errors **Cause:** Invalid or expired API key. **Solution:** 1. Generate a new API key at 2. Update the JULES_API_KEY environment variable 3. Note: You can have at most 3 API keys at a time ### Session Stuck in AWAITING_PLAN_APPROVAL **Cause:** Session was created with requirePlanApproval: true. **Solution:** __CODE_BLOCK_26__ ### Task Fails with Vague Error **Cause:** Vague prompts may produce unexpected results. **Solution:** - Write clear, specific prompts - Break large tasks into smaller, focused tasks - Avoid prompts that require long-running commands (dev servers, watch scripts) ### Large Files Skipped **Cause:** Files exceeding 768,000 tokens may be skipped. **Solution:** - Break down operations on very large files - Consider splitting large files before processing ## Best Practices ### Writing Effective Prompts 1. **Be specific**: Instead of "fix the bug", say "fix the null pointer exception in auth.js:45 when email is undefined" 2. **Provide context**: Mention relevant files, functions, or error messages 3. **Keep tasks focused**: One logical task per session ### Monitoring Sessions 1. Poll session state to track progress 2. Check activities for detailed progress updates 3. Handle AWAITING_USER_FEEDBACK state by sending clarifying messages ### Security 1. Never include secrets or credentials in prompts 2. Review generated PRs before merging 3. Use requirePlanApproval: true for sensitive operations ### Performance 1. Use automationMode: AUTO_CREATE_PR for streamlined workflows 2. Let plans auto-approve for routine tasks 3. Break complex tasks into smaller sessions ## Extracting Results When a session completes, retrieve the PR URL from outputs: __CODE_BLOCK_27__ ## Known Limitations - **Alpha API**: Specifications may change; API keys and definitions are experimental - **No long-running commands**: Jules cannot run npm run dev` or similar watch scripts

• Context size: Files > 768,000 tokens may be skipped
• Prompt sensitivity: Vague prompts may produce unexpected results

References

• [Jules API Documentation]()
• [Sessions Reference]()
• [Activities Reference]()
• [Sources Reference]()
• [Types Reference]()
• [Google Developers - Jules API]()
• [Jules Settings (API Keys)]()