Jules API Skill

Interact with the Google Jules AI coding agent via its REST API. Jules can autonomously execute coding tasks on your GitHub repositories — writing code, fixing bugs, adding tests, and creating pull requests.

Base URL: https://jules.googleapis.com/v1alpha

Auth: Pass your API key via the x-goog-api-key header. Get one at jules.google.com/settings.

List Sources (Connected Repositories)

Discover which GitHub repos are connected to your Jules account:

curl -s -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sources?pageSize=30"

With pagination:

curl -s -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sources?pageSize=10&pageToken=PAGE_TOKEN"

Filter specific sources:

curl -s -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sources?filter=name%3Dsources%2Fgithub-owner-repo"

Get a Source

Get details and branches for a specific repo:

curl -s -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sources/SOURCE_ID"

Example: sources/github-myorg-myrepo — replace with your actual source ID from List Sources.

Create a Session (Start a Coding Task)

Create a new Jules session to execute a coding task on a repo:

curl -s -X POST \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "TASK_DESCRIPTION",
    "title": "OPTIONAL_TITLE",
    "sourceContext": {
      "source": "sources/github-OWNER-REPO",
      "githubRepoContext": {
        "startingBranch": "main"
      }
    },
    "requirePlanApproval": true
  }' \
  "https://jules.googleapis.com/v1alpha/sessions"

Parameters

| Parameter | Required | Description |

|---|---|---|

| prompt | Yes | The task description for Jules to execute |

| title | No | Optional title (auto-generated if omitted) |

| sourceContext.source | Yes | Source resource name (e.g. sources/github-owner-repo) |

| sourceContext.githubRepoContext.startingBranch | Yes | Branch to start from (e.g. main, develop) |

| requirePlanApproval | No | If true, plans need explicit approval before execution |

| automationMode | No | Set to AUTO_CREATE_PR to auto-create PRs when done |

Auto-approve + Auto-PR example

curl -s -X POST \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Add comprehensive unit tests for the auth module",
    "sourceContext": {
      "source": "sources/github-myorg-myrepo",
      "githubRepoContext": { "startingBranch": "main" }
    },
    "automationMode": "AUTO_CREATE_PR"
  }' \
  "https://jules.googleapis.com/v1alpha/sessions"

List Sessions

List all your Jules sessions:

curl -s -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions?pageSize=10"

Paginate with pageToken:

curl -s -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions?pageSize=10&pageToken=NEXT_PAGE_TOKEN"

Get a Session

Retrieve a single session by ID (includes outputs like PRs if completed):

curl -s -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID"

Session States

| State | Meaning |

|---|---|

| QUEUED | Waiting to be processed |

| PLANNING | Jules is analyzing and creating a plan |

| AWAITING_PLAN_APPROVAL | Plan ready, waiting for user approval |

| AWAITING_USER_FEEDBACK | Jules needs additional input |

| IN_PROGRESS | Jules is actively working |

| PAUSED | Session is paused |

| COMPLETED | Task completed successfully |

| FAILED | Task failed to complete |

Approve a Plan

When a session is in AWAITING_PLAN_APPROVAL state, approve the plan:

curl -s -X POST \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID:approvePlan"

Send a Message

Send feedback, answer questions, or give additional instructions to an active session:

curl -s -X POST \
  -H "x-goog-api-key: $JULES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "YOUR_MESSAGE_HERE"
  }' \
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID:sendMessage"

Use this when session state is AWAITING_USER_FEEDBACK or to provide additional guidance during IN_PROGRESS.

List Activities (Monitor Progress)

Get all events/progress for a session:

curl -s -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID/activities?pageSize=50"

Get activities after a specific timestamp (for polling):

curl -s -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID/activities?createTime=2026-01-17T00:03:53Z"

Activity Types

Activities will contain exactly one of these event fields:

| Event | Description |

|---|---|

| planGenerated | Jules created a plan (contains plan.steps[]) |

| planApproved | A plan was approved |

| userMessaged | User sent a message |

| agentMessaged | Jules sent a message |

| progressUpdated | Status update during execution |

| sessionCompleted | Session finished successfully |

| sessionFailed | Session encountered an error (contains reason) |

Artifacts

Activities may include artifacts:

• ChangeSet: Code changes with gitPatch (unified diff, base commit, suggested commit message)
• BashOutput: Command output with command, output, exitCode
• Media: Binary output with mimeType and base64 data

Get a Single Activity

curl -s -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID/activities/ACTIVITY_ID"

Delete a Session

curl -s -X DELETE \
  -H "x-goog-api-key: $JULES_API_KEY" \
  "https://jules.googleapis.com/v1alpha/sessions/SESSION_ID"

Typical Workflow

1. List sources to find the repo resource name
2. Create a session with a prompt describing the task
3. Poll the session (Get Session) to track state changes
4. List activities to monitor progress and read Jules' messages
5. If requirePlanApproval was set, approve the plan when state is AWAITING_PLAN_APPROVAL
6. If state is AWAITING_USER_FEEDBACK, send a message with your response
7. When COMPLETED, get the session to find the output PR URL

Error Handling

| Code | Meaning |

|---|---|

| 200 | Success |

| 400 | Bad request (invalid parameters) |

| 401 | Unauthorized (invalid/missing API key) |

| 403 | Forbidden (insufficient permissions) |

| 404 | Not found |

| 429 | Rate limited |

| 500 | Server error |

Error responses return:

{
  "error": {
    "code": 400,
    "message": "Invalid session ID format",
    "status": "INVALID_ARGUMENT"
  }
}

Notes

• Get your API key from jules.google.com/settings
• Store it as the JULES_API_KEY environment variable
• Sources (repos) are connected via the Jules web UI at jules.google — the API is read-only for sources
• Session resource names follow the pattern sessions/{sessionId}
• Activity resource names follow sessions/{sessionId}/activities/{activityId}
• All list endpoints support pageSize (1-100) and pageToken for pagination