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

x-goog-api-key

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

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

prompt

title

sourceContext.source

sources/github-owner-repo

sourceContext.githubRepoContext.startingBranch

main

develop

requirePlanApproval

true

automationMode

AUTO_CREATE_PR

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

QUEUED

PLANNING

AWAITING_PLAN_APPROVAL

AWAITING_USER_FEEDBACK

IN_PROGRESS

PAUSED

COMPLETED

FAILED

Approve a Plan

When a session is in

AWAITING_PLAN_APPROVAL

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

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:

planGenerated

plan.steps[]

planApproved

userMessaged

agentMessaged

progressUpdated

sessionCompleted

sessionFailed

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

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