---
title: "Provider API"
description: "Every namespace on a provider, and the methods in each."
canonical_url: "https://docs-oquac2tli-poetry.vercel.app/reference/provider-api"
---
# Provider API

> Every namespace on a provider, and the methods in each.

Every provider has the namespaces below. A method for an operation that the forge lacks rejects with `UnsupportedOperationError`. Check [`can()`](https://docs-oquac2tli-poetry.vercel.app/guides/capabilities) first.

Listings come in pairs. `list()` returns an async iterable, and `listPage()` returns one `Page`. The tables show the iterable name and leave out its `Page` twin. See [Page through results](https://docs-oquac2tli-poetry.vercel.app/guides/pagination).

## Provider

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        kind
      </code>
      
      , <code>
        instance
      </code>
      
      , <code>
        baseUrl
      </code>
    </td>
    
    <td>
      The forge and deployment that the provider sends requests to
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        capabilities
      </code>
    </td>
    
    <td>
      What the provider supports, computed without a request
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        can(verb, kind?)
      </code>
    </td>
    
    <td>
      Whether an operation is supported
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        refreshCapabilities()
      </code>
    </td>
    
    <td>
      Reads the instance version and updates <code>
        capabilities
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        scopesFor(verb)
      </code>
    </td>
    
    <td>
      The scopes or permissions an operation needs
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        request()
      </code>
    </td>
    
    <td>
      A request with the provider's auth, for endpoints the model doesn't cover
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        urlFor(target)
      </code>
    </td>
    
    <td>
      The web URL of a repo, thread, comment, release, file or comparison
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parseUrl(url)
      </code>
    </td>
    
    <td>
      Reads a web URL on this instance into refs
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        referenceTo(ref, options?)
      </code>
    </td>
    
    <td>
      How to mention a thread in Markdown, such as <code>
        #42
      </code>
      
       or <code>
        !42
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        normaliseMarkdown(body)
      </code>
    </td>
    
    <td>
      Rewrites Markdown into the dialect the forge renders
    </td>
  </tr>
</tbody>
</table>

## `repos`

<table>
<thead>
  <tr>
    <th>
      Method
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        get(ref)
      </code>
    </td>
    
    <td>
      One repository
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        list(options?)
      </code>
    </td>
    
    <td>
      The account's repositories, or the installation's under app auth
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        labels(repo)
      </code>
      
      , <code>
        createLabel(repo, label)
      </code>
    </td>
    
    <td>
      Labels defined on a repository
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        milestones(repo)
      </code>
    </td>
    
    <td>
      Milestones
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        collaborators(repo)
      </code>
      
      , <code>
        addCollaborator(repo, actor, role)
      </code>
    </td>
    
    <td>
      Collaborators
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        permissionFor(repo, actor)
      </code>
    </td>
    
    <td>
      One account's role, or <code>
        'none'
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        assignableUsers(repo)
      </code>
    </td>
    
    <td>
      Accounts that can be assigned
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reviewerCandidates(ref)
      </code>
    </td>
    
    <td>
      Accounts that can review a pull request
    </td>
  </tr>
</tbody>
</table>

## `threads`

Reads:

<table>
<thead>
  <tr>
    <th>
      Method
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        get(ref)
      </code>
      
      , <code>
        getMany(refs)
      </code>
    </td>
    
    <td>
      One thread, or several in a batch
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        list(repo, query?)
      </code>
    </td>
    
    <td>
      Threads in a repository
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        events(ref)
      </code>
    </td>
    
    <td>
      Events on a thread
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        comments(ref)
      </code>
    </td>
    
    <td>
      Conversation comments
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reactions(target)
      </code>
    </td>
    
    <td>
      Reactions on a thread or a comment
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        checks(ref)
      </code>
    </td>
    
    <td>
      Every check on a pull request's head
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reviews(ref)
      </code>
    </td>
    
    <td>
      Reviews on a pull request
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        files(ref)
      </code>
      
      , <code>
        commits(ref)
      </code>
    </td>
    
    <td>
      Files and commits of a pull request
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        subscription(ref)
      </code>
    </td>
    
    <td>
      The account's subscription to a thread
    </td>
  </tr>
</tbody>
</table>

Writes:

<table>
<thead>
  <tr>
    <th>
      Method
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        create(repo, input)
      </code>
      
      , <code>
        update(ref, input)
      </code>
    </td>
    
    <td>
      Create or edit an issue or pull request
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        comment(ref, body)
      </code>
      
      , <code>
        editComment()
      </code>
      
      , <code>
        deleteComment()
      </code>
    </td>
    
    <td>
      Comments
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        upsertComment(ref, { key, body })
      </code>
    </td>
    
    <td>
      Create a comment, or edit the one an earlier call left behind
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        close(ref, options?)
      </code>
      
      , <code>
        reopen(ref)
      </code>
    </td>
    
    <td>
      Thread state
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        setLabels()
      </code>
      
      , <code>
        addLabels()
      </code>
      
      , <code>
        removeLabels()
      </code>
    </td>
    
    <td>
      Labels
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        setMilestone()
      </code>
      
      , <code>
        setAssignees()
      </code>
      
      , <code>
        requestReview()
      </code>
    </td>
    
    <td>
      Planning
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        react()
      </code>
      
      , <code>
        unreact()
      </code>
    </td>
    
    <td>
      Reactions
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        merge(ref, options?)
      </code>
      
      , <code>
        approveAndMerge(ref, options?)
      </code>
    </td>
    
    <td>
      Merge a pull request
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        createReview()
      </code>
      
      , <code>
        submitReview()
      </code>
      
      , <code>
        approve()
      </code>
    </td>
    
    <td>
      Reviews
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        resolveReviewThread()
      </code>
      
      , <code>
        unresolveReviewThread()
      </code>
    </td>
    
    <td>
      Review conversations
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        transfer()
      </code>
      
      , <code>
        markDuplicate()
      </code>
    </td>
    
    <td>
      Move or deduplicate
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        subscribe()
      </code>
      
      , <code>
        unsubscribe()
      </code>
    </td>
    
    <td>
      Change the account's subscription
    </td>
  </tr>
</tbody>
</table>

## `notifications`

`list()`, `markRead()`, `markDone()`, `unsubscribe()`, `markAllRead()`, `markAllDone()` and `unreadCount()`.

## `checks` and `ci`

<table>
<thead>
  <tr>
    <th>
      Method
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        checks.list(repo, sha)
      </code>
    </td>
    
    <td>
      Every check on a commit
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        checks.report(repo, sha, input)
      </code>
    </td>
    
    <td>
      Write a commit status, or a check run under GitHub App auth
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        checks.rerun(ref)
      </code>
    </td>
    
    <td>
      Re-run a check
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ci.runs(repo, query?)
      </code>
      
      , <code>
        ci.run(ref)
      </code>
    </td>
    
    <td>
      Workflow or pipeline runs
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ci.jobs(ref)
      </code>
      
      , <code>
        ci.log(ref)
      </code>
    </td>
    
    <td>
      Jobs of a run, and a job's log as a stream
    </td>
  </tr>
</tbody>
</table>

CI is read-only. There is no workflow dispatch.

## `contents`

<table>
<thead>
  <tr>
    <th>
      Method
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        file(repo, path, options?)
      </code>
    </td>
    
    <td>
      One file, as text or bytes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tree(repo, options?)
      </code>
    </td>
    
    <td>
      A directory, or every descendant with <code>
        recursive
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        branches(repo)
      </code>
      
      , <code>
        tags(repo)
      </code>
    </td>
    
    <td>
      Branches and tags
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        resolveRef(repo, ref)
      </code>
    </td>
    
    <td>
      A branch, tag or sha as a full sha
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        commits(repo, query?)
      </code>
      
      , <code>
        commit(repo, sha)
      </code>
    </td>
    
    <td>
      History, and one commit with its files
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        compare(repo, base, head)
      </code>
    </td>
    
    <td>
      Commits and files between two refs
    </td>
  </tr>
</tbody>
</table>

## `releases`

`list()`, `get()`, `getByTag()`, `latest()` and `downloadAsset()`. `latest()` returns the most recent release that isn't a draft or prerelease.

## `webhooks`

<table>
<thead>
  <tr>
    <th>
      Method
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ingest(delivery)
      </code>
    </td>
    
    <td>
      Verify a delivery and translate it into events
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        verify(delivery)
      </code>
    </td>
    
    <td>
      Check the signature only
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        events
      </code>
    </td>
    
    <td>
      Kinds and actions this provider can deliver
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        list(target)
      </code>
      
      , <code>
        create()
      </code>
      
      , <code>
        update()
      </code>
      
      , <code>
        delete()
      </code>
    </td>
    
    <td>
      Manage registered hooks
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        rotateSecret(ref, secret)
      </code>
    </td>
    
    <td>
      Replace a hook's signing secret
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        deliveries(ref)
      </code>
      
      , <code>
        redeliver(ref)
      </code>
    </td>
    
    <td>
      Read the delivery log, and send a delivery again
    </td>
  </tr>
</tbody>
</table>

## `search`

`threads()`, `repos()` and `commits()` search across repositories. A filter that the forge can't apply comes back as a `filter_unsupported` warning.

## Other namespaces

<table>
<thead>
  <tr>
    <th>
      Namespace
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        securityAlerts.list(repo, options?)
      </code>
    </td>
    
    <td>
      Dependency, code scanning and secret alerts
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        installations
      </code>
    </td>
    
    <td>
      List app installations, mint tokens and get a provider for each installation
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        users.get(login)
      </code>
    </td>
    
    <td>
      One account by login
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sources.subscribe(options?)
      </code>
    </td>
    
    <td>
      Live events over a long-lived connection
    </td>
  </tr>
</tbody>
</table>

## `Forges`

`createForges()` returns an object that routes calls. See [Work with several forges](https://docs-oquac2tli-poetry.vercel.app/guides/multiple-forges).

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        providers
      </code>
      
      , <code>
        get()
      </code>
      
      , <code>
        all()
      </code>
      
      , <code>
        for()
      </code>
      
      , <code>
        forUrl()
      </code>
    </td>
    
    <td>
      Find providers
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        parseUrl(url)
      </code>
    </td>
    
    <td>
      Read a web URL on any registered instance
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        notifications.list()
      </code>
    </td>
    
    <td>
      Notifications from every provider
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        repos.get()
      </code>
      
      , <code>
        threads.get()
      </code>
      
      , <code>
        threads.getMany()
      </code>
    </td>
    
    <td>
      Reads routed by ref
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        releases.list()
      </code>
      
      , <code>
        releases.latest()
      </code>
    </td>
    
    <td>
      Releases routed by repo
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        securityAlerts.list()
      </code>
    </td>
    
    <td>
      Alerts routed by repo
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        search.threads()
      </code>
      
      , <code>
        search.repos()
      </code>
    </td>
    
    <td>
      Search fanned out to every provider that supports it
    </td>
  </tr>
</tbody>
</table>


## Sitemap

See the full [sitemap](https://docs-oquac2tli-poetry.vercel.app/sitemap.md) for all pages.