sourcehut

git.sr.ht API Documentation

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

Queries

gitWebhook

Returns details of a git webhook subscription by its ID.

Returns WebhookSubscription

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

gitWebhooks

Returns a list of git webhook subscriptions associated with a repository. 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. repositoryID - Int!
  2. cursor - Cursor
Example Query 
query gitWebhooks($repositoryID: Int!, $cursor: Cursor) {
    gitWebhooks(repositoryID: $repositoryID, cursor: $cursor) {
        results {
            ...WebhookSubscription
        }
        cursor
    }
}

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
        }
    }
}

redirectByDiskPath

@anoninternal

Returns Redirect

Arguments
  1. path - String!
Example Query 
query redirectByDiskPath($path: String!) {
    redirectByDiskPath(path: $path) {
        created
        name
        owner {
            ...Entity
        }
        originalPath
        repository {
            ...Repository
        }
    }
}

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
  2. filter - Filter
Example Query 
query repositories($cursor: Cursor, $filter: Filter) {
    repositories(cursor: $cursor, filter: $filter) {
        results {
            ...Repository
        }
        cursor
    }
}

repositoryByDiskPath

@anoninternal

Returns Repository

Arguments
  1. path - String!
Example Query 
query repositoryByDiskPath($path: String!) {
    repositoryByDiskPath(path: $path) {
        id
        created
        updated
        owner {
            ...Entity
        }
        name
        description
        visibility
        readme
        access
        acls {
            ...ACLCursor
        }
        objects {
            ...Object
        }
        references {
            ...ReferenceCursor
        }
        HEAD {
            ...Reference
        }
        log {
            ...CommitCursor
        }
        path {
            ...TreeEntry
        }
        revparse_single {
            ...Commit
        }
        repoPath
    }
}

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

createGitWebhook

Creates a git webhook. 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 - GitWebhookInput!
Example Query 
query createGitWebhook($config: GitWebhookInput!) {
    createGitWebhook(config: $config) {
        id
        events
        query
        url
        client {
            ...OAuthClient
        }
        deliveries {
            ...WebhookDeliveryCursor
        }
        sample
    }
}

createRepository

@access(scope:REPOSITORIES, kind:RW)

Creates a new git repository. If the cloneUrl parameter is specified, the repository will be cloned from the given URL.

Returns Repository

Arguments
  1. name - String!
  2. visibility - Visibility!
  3. description - String
  4. cloneUrl - String
Example Query 
query createRepository($name: String!, $visibility: Visibility!, $description: String, $cloneUrl: String) {
    createRepository(name: $name, visibility: $visibility, description: $description, cloneUrl: $cloneUrl) {
        id
        created
        updated
        owner {
            ...Entity
        }
        name
        description
        visibility
        readme
        access
        acls {
            ...ACLCursor
        }
        objects {
            ...Object
        }
        references {
            ...ReferenceCursor
        }
        HEAD {
            ...Reference
        }
        log {
            ...CommitCursor
        }
        path {
            ...TreeEntry
        }
        revparse_single {
            ...Commit
        }
        repoPath
    }
}

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
    }
}

deleteArtifact

@access(scope:OBJECTS, kind:RW)

Deletes an artifact.

Returns Artifact

Arguments
  1. id - Int!
Example Query 
query deleteArtifact($id: Int!) {
    deleteArtifact(id: $id) {
        id
        created
        filename
        checksum
        size
        url
    }
}

deleteGitWebhook

Deletes a git 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 deleteGitWebhook($id: Int!) {
    deleteGitWebhook(id: $id) {
        id
        events
        query
        url
        client {
            ...OAuthClient
        }
        deliveries {
            ...WebhookDeliveryCursor
        }
        sample
    }
}

deleteRepository

@access(scope:REPOSITORIES, kind:RW)

Deletes a git 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
        access
        acls {
            ...ACLCursor
        }
        objects {
            ...Object
        }
        references {
            ...ReferenceCursor
        }
        HEAD {
            ...Reference
        }
        log {
            ...CommitCursor
        }
        path {
            ...TreeEntry
        }
        revparse_single {
            ...Commit
        }
        repoPath
    }
}

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
    }
}

deliverGitHook

@internal

Delivers git webhooks. If it returns false, the push event should be rejected. Invoked by git.sr.ht-update-hook.

Returns Boolean!

Arguments
  1. input - GitEventInput!
Example Query 
query deliverGitHook($input: GitEventInput!) {
    deliverGitHook(input: $input) {
    }
}

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 git 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
        access
        acls {
            ...ACLCursor
        }
        objects {
            ...Object
        }
        references {
            ...ReferenceCursor
        }
        HEAD {
            ...Reference
        }
        log {
            ...CommitCursor
        }
        path {
            ...TreeEntry
        }
        revparse_single {
            ...Commit
        }
        repoPath
    }
}

uploadArtifact

@access(scope:OBJECTS, kind:RW)

Uploads an artifact. revspec must match a specific git tag, and the filename must be unique among artifacts for this repository.

Returns Artifact!

Arguments
  1. repoId - Int!
  2. revspec - String!
  3. file - Upload!
Example Query 
query uploadArtifact($repoId: Int!, $revspec: String!, $file: Upload!) {
    uploadArtifact(repoId: $repoId, revspec: $revspec, file: $file) {
        id
        created
        filename
        checksum
        size
        url
    }
}

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. OBJECTS
  4. ACLS

Artifact

Arbitrary file attached to a git repository

Fields
  1. id - Int!
  2. created - Time!
  3. filename - String!
  4. checksum - String!
  5. size - Int!
  6. url - String!

ArtifactCursor

A cursor for enumerating artifacts

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 - [Artifact]!
  2. cursor - Cursor

BinaryBlob

Fields
  1. type - ObjectType!
  2. id - String!
  3. shortId - String!
  4. raw - String!
  5. base64 - String!

Blob

Fields
  1. id - String!

Boolean

The Boolean scalar type represents true or false.

Commit

Fields
  1. type - ObjectType!
  2. id - String!
  3. shortId - String!
  4. raw - String!
  5. author - Signature!
  6. committer - Signature!
  7. message - String!
  8. tree - Tree!
  9. parents - [Commit]!
  10. diff - String!

CommitCursor

A cursor for enumerating commits

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 - [Commit]!
  2. cursor - Cursor

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!

Filter

Fields
  1. count - Int
    • Number of results to return.
  2. search - String
    • Search terms. The exact meaning varies by usage, but generally these are compatible with the web UI's search syntax.

Float

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

GitEvent

This event is used for pre-receive and post-receive git hooks.

Fields
  1. uuid - String!
  2. event - WebhookEvent!
  3. date - Time!
  4. repository - Repository!
    • @access(scope:REPOSITORIES, kind:RO)
  5. pusher - Entity!
  6. updates - [UpdatedRef]!

GitEventInput

Fields
  1. repositoryID - Int!
  2. event - WebhookEvent!
  3. updates - [UpdatedRefInput]!

GitWebhookInput

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

GitWebhookSubscription

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

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.

OAuthClient

Fields
  1. uuid - String!

Object

Fields
  1. type - ObjectType!
  2. id - String!
  3. shortId - String!
  4. raw - String!
    • Raw git object, base64 encoded

ObjectType

Enum Values
  1. COMMIT
  2. TREE
  3. BLOB
  4. TAG

Redirect

Fields
  1. created - Time!
  2. name - String!
  3. owner - Entity!
  4. originalPath - String!
  5. repository - Repository

Reference

Fields
  1. name - String!
  2. target - String!
  3. follow - Object
  4. artifacts - ArtifactCursor!

ReferenceCursor

A cursor for enumerating a list of references

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 - [Reference]!
  2. cursor - Cursor

RepoInput

Fields
  1. name - String
  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. HEAD - String
    • Updates the repository HEAD reference, which serves as the default branch. Must be a valid branch name.

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. access - AccessMode!
    • The access that applies to this user for this repository
  10. acls - ACLCursor!
  11. objects - [Object]!
  12. references - ReferenceCursor!
  13. HEAD - Reference
    • The HEAD reference for this repository (equivalent to the default branch)
  14. log - CommitCursor!
    • Returns a list of comments sorted by committer time (similar to `git log`'s default ordering). If `from` is specified, it is interpreted as a revspec to start logging from. A clever reader may notice that using commits[-1].from + "^" as the from parameter is equivalent to passing the cursor to the next call.
  15. path - TreeEntry
    • Returns a tree entry for a given path, at the given revspec.
  16. revparse_single - Commit
    • Returns the commit for a given revspec.
  17. repoPath - String!

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!

Settings

Instance specific settings

Fields
  1. sshUser - String!

Signature

Fields
  1. name - String!
  2. email - String!
  3. time - Time!

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. type - ObjectType!
  2. id - String!
  3. shortId - String!
  4. raw - String!
  5. target - Object!
  6. name - String!
  7. tagger - Signature!
  8. message - String

TextBlob

Fields
  1. type - ObjectType!
  2. id - String!
  3. shortId - String!
  4. raw - String!
  5. text - String!

Time

Tree

Fields
  1. type - ObjectType!
  2. id - String!
  3. shortId - String!
  4. raw - String!
  5. entries - TreeEntryCursor!
  6. entry - TreeEntry

TreeEntry

Fields
  1. id - String!
  2. name - String!
  3. object - Object!
  4. mode - Int!
    • Unix-style file mode, i.e. 0755 or 0644 (octal)

TreeEntryCursor

A cursor for enumerating tree 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 - [TreeEntry]!
  2. cursor - Cursor

UpdatedRef

Fields
  1. ref - Reference
  2. old - Object
  3. new - Object
  4. log - CommitCursor
    • Note: this only returns up to the most recent 50 commits included in the update, i.e. old..new or new~50..new, whichever has fewer commits.
  5. diff - String
    • Difference from old..new in the unified diff format. This field is null if the diff requires more than one second to prepare.

UpdatedRefInput

Fields
  1. ref - String!
  2. old - String!
  3. new - String!

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
  4. GIT_PRE_RECEIVE
  5. GIT_POST_RECEIVE

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.

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

@anoninternal

@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

@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.