sourcehut

hg.sr.ht API Documentation

This is the GraphQL API documentation for the SourceHut service hg.sr.ht. It was generated from the service's GraphQL Schema definition.

Queries

me

@access(scope:PROFILE, kind:RO)

Returns the authenticated user.

Returns User!

Example Query 
query me {
    me {
        id
        created
        updated
        canonicalName
        username
        email
        url
        location
        bio
        repository {
            ...Repository
        }
        repositories {
            ...RepositoryCursor
        }
    }
}

repositories

@access(scope:REPOSITORIES, kind:RO)

Returns repositories that the authenticated user has access to.

NOTE: in this version of the API, only repositories owned by the authenticated user are returned, but in the future the default behavior will be to return all repositories that the user either (1) has been given explicit access to via ACLs or (2) has implicit access to either by ownership or group membership.

Returns RepositoryCursor

Arguments
  1. cursor - Cursor
Example Query 
query repositories($cursor: Cursor) {
    repositories(cursor: $cursor) {
        results {
            ...Repository
        }
        cursor
    }
}

user

@access(scope:PROFILE, kind:RO)

Returns a specific user.

Returns User

Arguments
  1. username - String!
Example Query 
query user($username: String!) {
    user(username: $username) {
        id
        created
        updated
        canonicalName
        username
        email
        url
        location
        bio
        repository {
            ...Repository
        }
        repositories {
            ...RepositoryCursor
        }
    }
}

userWebhook

Returns details of a user webhook subscription by its ID.

Returns WebhookSubscription

Arguments
  1. id - Int!
Example Query 
query userWebhook($id: Int!) {
    userWebhook(id: $id) {
        id
        events
        query
        url
        client {
            ...OAuthClient
        }
        deliveries {
            ...WebhookDeliveryCursor
        }
        sample
    }
}

userWebhooks

Returns a list of user webhook subscriptions. For clients authenticated with a personal access token, this returns all webhooks configured by all GraphQL clients for your account. For clients authenticated with an OAuth 2.0 access token, this returns only webhooks registered for your client.

Returns WebhookSubscriptionCursor!

Arguments
  1. cursor - Cursor
Example Query 
query userWebhooks($cursor: Cursor) {
    userWebhooks(cursor: $cursor) {
        results {
            ...WebhookSubscription
        }
        cursor
    }
}

version

Returns API version information.

Returns Version!

Example Query 
query version {
    version {
        major
        minor
        patch
        deprecationDate
        features {
            ...Features
        }
        settings {
            ...Settings
        }
    }
}

webhook

Returns information about the webhook currently being processed. This is not valid during normal queries over HTTP, and will return an error if used outside of a webhook context.

Returns WebhookPayload!

Example Query 
query webhook {
    webhook {
        uuid
        event
        date
    }
}

Mutations

createRepository

@access(scope:REPOSITORIES, kind:RW)

Creates a new mercurial repository

Returns Repository!

Arguments
  1. name - String!
  2. visibility - Visibility!
  3. description - String
Example Query 
query createRepository($name: String!, $visibility: Visibility!, $description: String) {
    createRepository(name: $name, visibility: $visibility, description: $description) {
        id
        created
        updated
        owner {
            ...Entity
        }
        name
        description
        visibility
        readme
        nonPublishing
        accessControlList {
            ...ACLCursor
        }
        tip {
            ...Revision
        }
        heads {
            ...RevisionCursor
        }
        log {
            ...RevisionCursor
        }
        bookmarks {
            ...NamedRevisionCursor
        }
        branches {
            ...NamedRevisionCursor
        }
        tags {
            ...NamedRevisionCursor
        }
        files {
            ...FileCursor
        }
        cat
    }
}

createUserWebhook

Creates a new user webhook subscription. When an event from the provided list of events occurs, the 'query' parameter (a GraphQL query) will be evaluated and the results will be sent to the provided URL as the body of an HTTP POST request. The list of events must include at least one event, and no duplicates.

This query is evaluated in the webhook context, such that query { webhook } may be used to access details of the event which trigged the webhook. The query may not make any mutations.

Returns WebhookSubscription!

Arguments
  1. config - UserWebhookInput!
Example Query 
query createUserWebhook($config: UserWebhookInput!) {
    createUserWebhook(config: $config) {
        id
        events
        query
        url
        client {
            ...OAuthClient
        }
        deliveries {
            ...WebhookDeliveryCursor
        }
        sample
    }
}

deleteACL

@access(scope:ACLS, kind:RW)

Deletes an entry from the access control list

Returns ACL!

Arguments
  1. id - Int!
Example Query 
query deleteACL($id: Int!) {
    deleteACL(id: $id) {
        id
        created
        repository {
            ...Repository
        }
        entity {
            ...Entity
        }
        mode
    }
}

deleteRepository

@access(scope:REPOSITORIES, kind:RW)

Deletes a mercurial repository

Returns Repository!

Arguments
  1. id - Int!
Example Query 
query deleteRepository($id: Int!) {
    deleteRepository(id: $id) {
        id
        created
        updated
        owner {
            ...Entity
        }
        name
        description
        visibility
        readme
        nonPublishing
        accessControlList {
            ...ACLCursor
        }
        tip {
            ...Revision
        }
        heads {
            ...RevisionCursor
        }
        log {
            ...RevisionCursor
        }
        bookmarks {
            ...NamedRevisionCursor
        }
        branches {
            ...NamedRevisionCursor
        }
        tags {
            ...NamedRevisionCursor
        }
        files {
            ...FileCursor
        }
        cat
    }
}

deleteUser

@internal

Deletes the authenticated user's account. Internal use only.

Returns Int!

Example Query 
query deleteUser {
    deleteUser {
    }
}

deleteUserWebhook

Deletes a user webhook. Any events already queued may still be delivered after this request completes. Clients authenticated with a personal access token may delete any webhook registered for their account, but authorized OAuth 2.0 clients may only delete their own webhooks. Manually deleting a webhook configured by a third-party client may cause unexpected behavior with the third-party integration.

Returns WebhookSubscription!

Arguments
  1. id - Int!
Example Query 
query deleteUserWebhook($id: Int!) {
    deleteUserWebhook(id: $id) {
        id
        events
        query
        url
        client {
            ...OAuthClient
        }
        deliveries {
            ...WebhookDeliveryCursor
        }
        sample
    }
}

updateACL

@access(scope:ACLS, kind:RW)

Adds or updates a user in the access control list

Returns ACL!

Arguments
  1. repoId - Int!
  2. mode - AccessMode!
  3. entity - ID!
Example Query 
query updateACL($repoId: Int!, $mode: AccessMode!, $entity: ID!) {
    updateACL(repoId: $repoId, mode: $mode, entity: $entity) {
        id
        created
        repository {
            ...Repository
        }
        entity {
            ...Entity
        }
        mode
    }
}

updateRepository

@access(scope:REPOSITORIES, kind:RW)

Updates the metadata for a mercurial repository

Returns Repository!

Arguments
  1. id - Int!
  2. input - RepoInput!
Example Query 
query updateRepository($id: Int!, $input: RepoInput!) {
    updateRepository(id: $id, input: $input) {
        id
        created
        updated
        owner {
            ...Entity
        }
        name
        description
        visibility
        readme
        nonPublishing
        accessControlList {
            ...ACLCursor
        }
        tip {
            ...Revision
        }
        heads {
            ...RevisionCursor
        }
        log {
            ...RevisionCursor
        }
        bookmarks {
            ...NamedRevisionCursor
        }
        branches {
            ...NamedRevisionCursor
        }
        tags {
            ...NamedRevisionCursor
        }
        files {
            ...FileCursor
        }
        cat
    }
}

Definitions

ACL

Fields
  1. id - Int!
  2. created - Time!
  3. repository - Repository!
  4. entity - Entity!
  5. mode - AccessMode

ACLCursor

A cursor for enumerating access control list entries

If there are additional results available, the cursor object may be passed back into the same endpoint to retrieve another page. If the cursor is null, there are no remaining results to return.

Fields
  1. results - [ACL]!
  2. cursor - Cursor

AccessKind

Enum Values
  1. RO
  2. RW

AccessMode

Enum Values
  1. RO
    • Read-only
  2. RW
    • Read/write

AccessScope

Enum Values
  1. PROFILE
  2. REPOSITORIES
  3. REVISIONS
  4. ACLS

Boolean

The Boolean scalar type represents true or false.

Cursor

Entity

Fields
  1. id - Int!
  2. created - Time!
  3. updated - Time!
  4. canonicalName - String!
    • The canonical name of this entity. For users, this is their username prefixed with '~'. Additional entity types will be supported in the future.
  5. repository - Repository
    • @access(scope:REPOSITORIES, kind:RO)
    • Returns a specific repository owned by the entity.
  6. repositories - RepositoryCursor!
    • @access(scope:REPOSITORIES, kind:RO)
    • Returns a list of repositories owned by the entity.

Features

Describes the status of optional features

Fields
  1. artifacts - Boolean!

File

Fields
  1. name - String!

FileCursor

A cursor for enumerating files in a repository

If there are additional results available, the cursor object may be passed back into the same endpoint to retrieve another page. If the cursor is null, there are no remaining results to return.

Fields
  1. results - [File]!
  2. cursor - Cursor

Float

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

ID

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

Int

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

NamedRevision

Fields
  1. name - String!
  2. id - String!

NamedRevisionCursor

A cursor for enumerating bookmarks, tags, and branches

If there are additional results available, the cursor object may be passed back into the same endpoint to retrieve another page. If the cursor is null, there are no remaining results to return.

Fields
  1. results - [NamedRevision]!
  2. cursor - Cursor

OAuthClient

Fields
  1. uuid - String!

RepoInput

Fields
  1. name - String
    • Omit these fields to leave them unchanged, or set them to null to clear their value.
  2. description - String
  3. visibility - Visibility
  4. readme - String
    • Updates the custom README associated with this repository. Note that the provided HTML will be sanitized when displayed on the web; see https://man.sr.ht/markdown/#post-processing
  5. nonPublishing - Boolean
    • Controls whether this repository is a non-publishing repository.

Repository

Fields
  1. id - Int!
  2. created - Time!
  3. updated - Time!
  4. owner - Entity!
  5. name - String!
  6. description - String
  7. visibility - Visibility!
  8. readme - String
    • The repository's custom README, if set. NOTICE: This returns unsanitized HTML. It is the client's responsibility to sanitize this for display on the web, if so desired.
  9. nonPublishing - Boolean!
    • Whether or not this repository is a non-publishing repository.
  10. accessControlList - ACLCursor!
  11. tip - Revision
    • @access(scope:REVISIONS, kind:RO)
    • The tip reference for this repository (latest commit)
  12. heads - RevisionCursor!
    • @access(scope:REVISIONS, kind:RO)
    • Returns the list of open heads in the repository (like `hg heads`) If `rev` is specified, return only open heads on the branch associated with the given revision (like `hg heads REV`)
  13. log - RevisionCursor!
    • @access(scope:REVISIONS, kind:RO)
    • Returns a list of commits (like `hg log`) If `rev` is specified, only show the given commit (like `hg log --rev REV`)
  14. bookmarks - NamedRevisionCursor!
    • @access(scope:REVISIONS, kind:RO)
    • Returns a list of bookmarks
  15. branches - NamedRevisionCursor!
    • @access(scope:REVISIONS, kind:RO)
    • Returns a list of branches
  16. tags - NamedRevisionCursor!
    • @access(scope:REVISIONS, kind:RO)
    • Returns a list of tags
  17. files - FileCursor!
    • @access(scope:REVISIONS, kind:RO)
    • Returns a list of files matching the given path
  18. cat - String
    • @access(scope:REVISIONS, kind:RO)
    • Returns the contents of a file given a relative path and an optional revset

RepositoryCursor

A cursor for enumerating a list of repositories

If there are additional results available, the cursor object may be passed back into the same endpoint to retrieve another page. If the cursor is null, there are no remaining results to return.

Fields
  1. results - [Repository]!
  2. cursor - Cursor

RepositoryEvent

Fields
  1. uuid - String!
  2. event - WebhookEvent!
  3. date - Time!
  4. repository - Repository!

Revision

Fields
  1. id - String!
  2. branch - String!
  3. tags - [String]!
  4. author - String!
  5. description - String!

RevisionCursor

A cursor for enumerating revisions

If there are additional results available, the cursor object may be passed back into the same endpoint to retrieve another page. If the cursor is null, there are no remaining results to return.

Fields
  1. results - [Revision]!
  2. cursor - Cursor

Settings

Instance specific settings

Fields
  1. sshUser - String!

String

The Stringscalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Tag

Fields
  1. name - String!
  2. id - String!

Time

Upload

User

Fields
  1. id - Int!
  2. created - Time!
  3. updated - Time!
  4. canonicalName - String!
  5. username - String!
  6. email - String!
  7. url - String
  8. location - String
  9. bio - String
  10. repository - Repository
    • @access(scope:REPOSITORIES, kind:RO)
  11. repositories - RepositoryCursor!
    • @access(scope:REPOSITORIES, kind:RO)

UserWebhookInput

Fields
  1. url - String!
  2. events - [WebhookEvent]!
  3. query - String!

UserWebhookSubscription

Fields
  1. id - Int!
  2. events - [WebhookEvent]!
  3. query - String!
  4. url - String!
  5. client - OAuthClient
  6. deliveries - WebhookDeliveryCursor!
  7. sample - String!

Version

Fields
  1. major - Int!
  2. minor - Int!
  3. patch - Int!
  4. deprecationDate - Time
    • If this API version is scheduled for deprecation, this is the date on which it will stop working; or null if this API version is not scheduled for deprecation.
  5. features - Features!
    • Optional features
  6. settings - Settings!
    • Config settings

Visibility

Enum Values
  1. PUBLIC
    • Visible to everyone, listed on your profile
  2. UNLISTED
    • Visible to everyone (if they know the URL), not listed on your profile
  3. PRIVATE
    • Not visible to anyone except those explicitly added to the access list

WebhookDelivery

Fields
  1. uuid - String!
  2. date - Time!
  3. event - WebhookEvent!
  4. subscription - WebhookSubscription!
  5. requestBody - String!
  6. responseBody - String
    • These details are provided only after a response is received from the remote server. If a response is sent whose Content-Type is not text/*, or cannot be decoded as UTF-8, the response body will be null. It will be truncated after 64 KiB.
  7. responseHeaders - String
  8. responseStatus - Int

WebhookDeliveryCursor

A cursor for enumerating a list of webhook deliveries

If there are additional results available, the cursor object may be passed back into the same endpoint to retrieve another page. If the cursor is null, there are no remaining results to return.

Fields
  1. results - [WebhookDelivery]!
  2. cursor - Cursor

WebhookEvent

Enum Values
  1. REPO_CREATED
  2. REPO_UPDATE
  3. REPO_DELETED

WebhookPayload

Fields
  1. uuid - String!
  2. event - WebhookEvent!
  3. date - Time!

WebhookSubscription

Fields
  1. id - Int!
  2. events - [WebhookEvent]!
  3. query - String!
  4. url - String!
  5. client - OAuthClient
    • If this webhook was registered by an authorized OAuth 2.0 client, this field is non-null.
  6. deliveries - WebhookDeliveryCursor!
    • All deliveries which have been sent to this webhook.
  7. sample - String!
    • Returns a sample payload for this subscription, for testing purposes

WebhookSubscriptionCursor

A cursor for enumerating a list of webhook subscriptions

If there are additional results available, the cursor object may be passed back into the same endpoint to retrieve another page. If the cursor is null, there are no remaining results to return.

Fields
  1. results - [WebhookSubscription]!
  2. cursor - Cursor

Directives

@access

Decorates fields for which access requires a particular OAuth 2.0 scope with read or write access. For the meta.sr.ht API, you have access to all public information without any special permissions - user profile information, public keys, and so on.

Arguments
  1. scope - AccessScope!
  2. kind - AccessKind!

@defer

Directs the executor to defer this fragment when the if argument is true or undefined.

Arguments
  1. if - Boolean
    • Deferred when true or undefined.
  2. label - String
    • Unique name

@deprecated

Marks an element of a GraphQL schema as no longer supported.

Arguments
  1. reason - String
    • Explains why this element was deprecated, usually also including a suggestion for how to access supported similar data. Formatted using the Markdown syntax, as specified by [CommonMark](https://commonmark.org/).

@include

Directs the executor to include this field or fragment only when the if argument is true.

Arguments
  1. if - Boolean!
    • Included when true.

@internal

This used to decorate fields which are for internal use, and are not available to normal API users.

@oneOf

Indicates exactly one field must be supplied and this field must not be null.

@private

This is used to decorate fields which are only accessible with a personal access token, and are not available to clients using OAuth 2.0 access tokens.

@scopehelp

Used to provide a human-friendly description of an access scope

Arguments
  1. details - String!

@skip

Directs the executor to skip this field or fragment when the if argument is true.

Arguments
  1. if - Boolean!
    • Skipped when true.

@specifiedBy

Exposes a URL that specifies the behavior of this scalar.

Arguments
  1. url - String!
    • The URL that specifies the behavior of this scalar.