## ParseContextURL

**post** `/gitpod.v1.RunnerService/ParseContextURL`

Parses a context URL and returns the parsed result.

Use this method to:

- Validate context URLs
- Check repository access
- Verify branch existence

Returns:

- FAILED_PRECONDITION if authentication is required
- PERMISSION_DENIED if access is not allowed
- INVALID_ARGUMENT if URL is invalid
- NOT_FOUND if repository/branch doesn't exist

### Examples

- Parse URL:

  Parses and validates a context URL.

  ```yaml
  contextUrl: "https://github.com/org/repo/tree/main"
  ```

### Body Parameters

- `contextUrl: optional string`

- `runnerId: optional string`

### Returns

- `git: optional object { branch, cloneUrl, commit, 5 more }`

  - `branch: optional string`

  - `cloneUrl: optional string`

  - `commit: optional string`

  - `host: optional string`

  - `owner: optional string`

  - `repo: optional string`

  - `tag: optional string`

  - `upstreamRemoteUrl: optional string`

- `issue: optional object { id, title }`

  - `id: optional string`

    id is the source system's ID of this issue, e.g. BNFRD-6100

  - `title: optional string`

- `originalContextUrl: optional string`

- `pr: optional object { id, fromBranch, title, toBranch }`

  Deprecated: Use top-level PullRequest message instead

  - `id: optional string`

  - `fromBranch: optional string`

  - `title: optional string`

  - `toBranch: optional string`

- `projectIds: optional array of string`

  project_ids is a list of projects to which the context URL belongs to.

- `pullRequest: optional object { id, author, draft, 6 more }`

  PullRequest represents pull request metadata from source control systems.
  This message is used across workflow triggers, executions, and agent contexts
  to maintain consistent PR information throughout the system.

  - `id: optional string`

    Unique identifier from the source system (e.g., "123" for GitHub PR #123)

  - `author: optional string`

    Author name as provided by the SCM system

  - `draft: optional boolean`

    Whether this is a draft pull request

  - `fromBranch: optional string`

    Source branch name (the branch being merged from)

  - `repository: optional object { cloneUrl, host, name, owner }`

    Repository information

    - `cloneUrl: optional string`

    - `host: optional string`

    - `name: optional string`

    - `owner: optional string`

  - `state: optional State`

    Current state of the pull request

    - `"STATE_UNSPECIFIED"`

    - `"STATE_OPEN"`

    - `"STATE_CLOSED"`

    - `"STATE_MERGED"`

  - `title: optional string`

    Pull request title

  - `toBranch: optional string`

    Target branch name (the branch being merged into)

  - `url: optional string`

    Pull request URL (e.g., "https://github.com/owner/repo/pull/123")

- `scmId: optional string`

  scm_id is the unique identifier of the SCM provider (e.g., "github", "gitlab", "bitbucket")

### Example

```http
curl https://app.gitpod.io/api/gitpod.v1.RunnerService/ParseContextURL \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'
```

#### Response

```json
{
  "git": {
    "branch": "branch",
    "cloneUrl": "cloneUrl",
    "commit": "commit",
    "host": "host",
    "owner": "owner",
    "repo": "repo",
    "tag": "tag",
    "upstreamRemoteUrl": "upstreamRemoteUrl"
  },
  "issue": {
    "id": "id",
    "title": "title"
  },
  "originalContextUrl": "originalContextUrl",
  "pr": {
    "id": "id",
    "fromBranch": "fromBranch",
    "title": "title",
    "toBranch": "toBranch"
  },
  "projectIds": [
    "string"
  ],
  "pullRequest": {
    "id": "id",
    "author": "author",
    "draft": true,
    "fromBranch": "fromBranch",
    "repository": {
      "cloneUrl": "cloneUrl",
      "host": "host",
      "name": "name",
      "owner": "owner"
    },
    "state": "STATE_UNSPECIFIED",
    "title": "title",
    "toBranch": "toBranch",
    "url": "url"
  },
  "scmId": "scmId"
}
```