sourcehut

hub.sr.ht API Documentation

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

To get started, also check out SourceHut's general GraphQL API conventions or try hub.sr.ht's GraphQL playground.

Queries

mailingList

@access(scope:LISTS, kind:RO)

Looks up a specific mailing list

Returns MailingList

Arguments
  1. rid - ID!
Example Query 
query mailingList($rid: ID!) {
    mailingList(rid: $rid) {
        rid
        linked
        updated
        owner {
            ...Entity
        }
        name
        description
        visibility
        projects {
            ...ProjectCursor
        }
    }
}

me

@access(scope:PROFILE, kind:RO)

Returns the authenticated user

Returns User!

Example Query 
query me {
    me {
        id
        canonicalName
        username
        project {
            ...Project
        }
        projects {
            ...ProjectCursor
        }
    }
}

project

@access(scope:PROJECTS, kind:RO)

Looks up a specific project

Returns Project

Arguments
  1. rid - ID!
Example Query 
query project($rid: ID!) {
    project(rid: $rid) {
        rid
        created
        updated
        ownerId
        owner {
            ...Entity
        }
        name
        description
        website
        visibility
        checklistComplete
        summaryRepoId
        tags
        mailingLists {
            ...MailingListCursor
        }
        sources {
            ...SourceRepoCursor
        }
        trackers {
            ...TrackerCursor
        }
        readme {
            ...SourceRepo
        }
        resource {
            ...ProjectResource
        }
        mailingList {
            ...MailingList
        }
        source {
            ...SourceRepo
        }
        tracker {
            ...Tracker
        }
    }
}

projects

@access(scope:PROJECTS, kind:RO)

List all public projects

Returns ProjectCursor!

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

resource

@access(scope:PROJECTS, kind:RO)

Looks up a specific resource

Returns ProjectResource

Arguments
  1. rid - ID!
Example Query 
query resource($rid: ID!) {
    resource(rid: $rid) {
        rid
        linked
        updated
        owner {
            ...Entity
        }
        name
        description
        visibility
        projects {
            ...ProjectCursor
        }
    }
}

source

@access(scope:SOURCES, kind:RO)

Looks up a specific source repository

Returns SourceRepo

Arguments
  1. rid - ID!
Example Query 
query source($rid: ID!) {
    source(rid: $rid) {
        rid
        linked
        updated
        owner {
            ...Entity
        }
        name
        description
        repoType
        visibility
        projects {
            ...ProjectCursor
        }
    }
}

tracker

@access(scope:TRACKERS, kind:RO)

Looks up a specific tracker

Returns Tracker

Arguments
  1. rid - ID!
Example Query 
query tracker($rid: ID!) {
    tracker(rid: $rid) {
        rid
        linked
        updated
        owner {
            ...Entity
        }
        name
        description
        visibility
        projects {
            ...ProjectCursor
        }
    }
}

user

@access(scope:PROFILE, kind:RO)

Looks up a specific user

Returns User

Arguments
  1. username - String!
Example Query 
query user($username: String!) {
    user(username: $username) {
        id
        canonicalName
        username
        project {
            ...Project
        }
        projects {
            ...ProjectCursor
        }
    }
}

version

Returns API version information.

Returns Version!

Example Query 
query version {
    version {
        major
        minor
        patch
        buildVersion
        buildDate
        deprecationDate
        features {
            ...Features
        }
    }
}

Mutations

createProject

@access(scope:PROJECTS, kind:RW)

Creates a new project.

Returns Project

Arguments
  1. name - String!
  2. visibility - Visibility!
  3. description - String
  4. tags - [String]
Example Query 
mutation createProject($name: String!, $visibility: Visibility!, $description: String, $tags: [String!]) {
    createProject(name: $name, visibility: $visibility, description: $description, tags: $tags) {
        rid
        created
        updated
        ownerId
        owner {
            ...Entity
        }
        name
        description
        website
        visibility
        checklistComplete
        summaryRepoId
        tags
        mailingLists {
            ...MailingListCursor
        }
        sources {
            ...SourceRepoCursor
        }
        trackers {
            ...TrackerCursor
        }
        readme {
            ...SourceRepo
        }
        resource {
            ...ProjectResource
        }
        mailingList {
            ...MailingList
        }
        source {
            ...SourceRepo
        }
        tracker {
            ...Tracker
        }
    }
}

deleteProject

@access(scope:PROJECTS, kind:RW)

Deletes an existing project.

Returns Project

Arguments
  1. rid - ID!
Example Query 
mutation deleteProject($rid: ID!) {
    deleteProject(rid: $rid) {
        rid
        created
        updated
        ownerId
        owner {
            ...Entity
        }
        name
        description
        website
        visibility
        checklistComplete
        summaryRepoId
        tags
        mailingLists {
            ...MailingListCursor
        }
        sources {
            ...SourceRepoCursor
        }
        trackers {
            ...TrackerCursor
        }
        readme {
            ...SourceRepo
        }
        resource {
            ...ProjectResource
        }
        mailingList {
            ...MailingList
        }
        source {
            ...SourceRepo
        }
        tracker {
            ...Tracker
        }
    }
}

deleteUser

@internal

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

Returns Int!

Example Query 
mutation deleteUser {
    deleteUser
}

linkMailingList

@access(scope:PROJECTS, kind:RW)

Links an existing mailing list to a project.

Returns MailingList

Arguments
  1. projectID - ID!
  2. listID - ID!
Example Query 
mutation linkMailingList($projectID: ID!, $listID: ID!) {
    linkMailingList(projectID: $projectID, listID: $listID) {
        rid
        linked
        updated
        owner {
            ...Entity
        }
        name
        description
        visibility
        projects {
            ...ProjectCursor
        }
    }
}

linkSource

@access(scope:PROJECTS, kind:RW)

Links an existing source repository to a project.

Returns SourceRepo

Arguments
  1. projectID - ID!
  2. sourceRepoID - ID!
Example Query 
mutation linkSource($projectID: ID!, $sourceRepoID: ID!) {
    linkSource(projectID: $projectID, sourceRepoID: $sourceRepoID) {
        rid
        linked
        updated
        owner {
            ...Entity
        }
        name
        description
        repoType
        visibility
        projects {
            ...ProjectCursor
        }
    }
}

linkTracker

@access(scope:PROJECTS, kind:RW)

Links an existing tracker to a project.

Returns Tracker

Arguments
  1. projectID - ID!
  2. trackerID - ID!
Example Query 
mutation linkTracker($projectID: ID!, $trackerID: ID!) {
    linkTracker(projectID: $projectID, trackerID: $trackerID) {
        rid
        linked
        updated
        owner {
            ...Entity
        }
        name
        description
        visibility
        projects {
            ...ProjectCursor
        }
    }
}

unlinkMailingList

@access(scope:PROJECTS, kind:RW)

Unlinks an existing mailing list from a project.

Returns MailingList

Arguments
  1. projectID - ID!
  2. listID - ID!
Example Query 
mutation unlinkMailingList($projectID: ID!, $listID: ID!) {
    unlinkMailingList(projectID: $projectID, listID: $listID) {
        rid
        linked
        updated
        owner {
            ...Entity
        }
        name
        description
        visibility
        projects {
            ...ProjectCursor
        }
    }
}

unlinkSource

@access(scope:PROJECTS, kind:RW)

Unlinks an existing source repository from a project.

Returns SourceRepo

Arguments
  1. projectID - ID!
  2. sourceRepoID - ID!
Example Query 
mutation unlinkSource($projectID: ID!, $sourceRepoID: ID!) {
    unlinkSource(projectID: $projectID, sourceRepoID: $sourceRepoID) {
        rid
        linked
        updated
        owner {
            ...Entity
        }
        name
        description
        repoType
        visibility
        projects {
            ...ProjectCursor
        }
    }
}

unlinkTracker

@access(scope:PROJECTS, kind:RW)

Unlinks an existing tracker from a project.

Returns Tracker

Arguments
  1. projectID - ID!
  2. trackerID - ID!
Example Query 
mutation unlinkTracker($projectID: ID!, $trackerID: ID!) {
    unlinkTracker(projectID: $projectID, trackerID: $trackerID) {
        rid
        linked
        updated
        owner {
            ...Entity
        }
        name
        description
        visibility
        projects {
            ...ProjectCursor
        }
    }
}

updateProject

@access(scope:PROJECTS, kind:RW)

Updates an existing project.

Returns Project

Arguments
  1. rid - ID!
  2. input - ProjectInput!
Example Query 
mutation updateProject($rid: ID!, $input: ProjectInput!) {
    updateProject(rid: $rid, input: $input) {
        rid
        created
        updated
        ownerId
        owner {
            ...Entity
        }
        name
        description
        website
        visibility
        checklistComplete
        summaryRepoId
        tags
        mailingLists {
            ...MailingListCursor
        }
        sources {
            ...SourceRepoCursor
        }
        trackers {
            ...TrackerCursor
        }
        readme {
            ...SourceRepo
        }
        resource {
            ...ProjectResource
        }
        mailingList {
            ...MailingList
        }
        source {
            ...SourceRepo
        }
        tracker {
            ...Tracker
        }
    }
}

Definitions

AccessKind

ENUM
Enum Values
  1. RO
  2. RW

AccessScope

ENUM
Enum Values
  1. PROFILE
  2. PROJECTS
  3. LISTS
  4. SOURCES
  5. TRACKERS

Boolean

SCALAR

The Boolean scalar type represents true or false.

Cursor

SCALAR

Entity

INTERFACE implemented by User
Fields
  1. canonicalName - String!

Features

OBJECT

Describes the status of optional features

Fields
  1. lists - Boolean!
  2. git - Boolean!
  3. hg - Boolean!
  4. todo - Boolean!

Float

SCALAR

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

ID

SCALAR

A unique identifier representing a resource available via the API, represented as an arbitrary, opaque string. These IDs are guaranteed to remain stable as a resource is renamed, moved between owners, etc. Often referred to as a "resource ID" or "rid".

Int

SCALAR

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

MailingList

OBJECT implements ProjectResource
Fields
  1. rid - ID!
  2. linked - Time!
  3. updated - Time!
  4. owner - Entity!
  5. name - String!
  6. description - String
  7. visibility - Visibility!
  8. projects(cursor: Cursor) - ProjectCursor!

MailingListCursor

OBJECT
Fields
  1. results - [MailingList]!
  2. cursor - Cursor

Project

OBJECT
Fields
  1. rid - ID!
  2. created - Time!
  3. updated - Time!
  4. ownerId - Int!
  5. owner - Entity!
  6. name - String!
  7. description - String
  8. website - String
  9. visibility - Visibility!
  10. checklistComplete - Boolean!
  11. summaryRepoId - Int
  12. tags - [String]!
  13. mailingLists(cursor: Cursor) - MailingListCursor!
  14. sources(cursor: Cursor) - SourceRepoCursor!
  15. trackers(cursor: Cursor) - TrackerCursor!
  16. readme - SourceRepo
  17. resource(rid: ID!) - ProjectResource
  18. mailingList(name: String!) - MailingList
  19. source(name: String!) - SourceRepo
  20. tracker(name: String!) - Tracker

ProjectCursor

OBJECT
Fields
  1. results - [Project]!
  2. cursor - Cursor

ProjectInput

INPUT_OBJECT
Fields
  1. name - String
  2. visibility - Visibility
  3. description - String
  4. website - String
  5. checklistComplete - Boolean
  6. readme - ID
  7. tags - [String]

ProjectResource

INTERFACE implemented by MailingList, SourceRepo, Tracker
Fields
  1. rid - ID!
  2. linked - Time!
  3. updated - Time!
  4. owner - Entity!
  5. name - String!
  6. description - String
  7. visibility - Visibility!
  8. projects(cursor: Cursor) - ProjectCursor!

RepoType

ENUM
Enum Values
  1. GIT
  2. HG

SourceRepo

OBJECT implements ProjectResource
Fields
  1. rid - ID!
  2. linked - Time!
  3. updated - Time!
  4. owner - Entity!
  5. name - String!
  6. description - String
  7. repoType - RepoType!
  8. visibility - Visibility!
  9. projects(cursor: Cursor) - ProjectCursor!

SourceRepoCursor

OBJECT
Fields
  1. results - [SourceRepo]!
  2. cursor - Cursor

String

SCALAR

The String scalar 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.

Time

SCALAR

String of the format %Y-%m-%dT%H:%M:%SZ

Tracker

OBJECT implements ProjectResource
Fields
  1. rid - ID!
  2. linked - Time!
  3. updated - Time!
  4. owner - Entity!
  5. name - String!
  6. description - String
  7. visibility - Visibility!
  8. projects(cursor: Cursor) - ProjectCursor!

TrackerCursor

OBJECT
Fields
  1. results - [Tracker]!
  2. cursor - Cursor

Upload

SCALAR

A file uploaded alongside the GraphQL request. This API is compatible with the multipart request specification for requests that include uploads:

https://github.com/jaydenseric/graphql-multipart-request-spec

User

OBJECT implements Entity
Fields
  1. id - Int!
  2. canonicalName - String!
  3. username - String!
  4. project(name: String!) - Project
  5. projects(cursor: Cursor) - ProjectCursor!

Version

OBJECT
Fields
  1. major - Int!
  2. minor - Int!
  3. patch - Int!
  4. buildVersion - String!
  5. buildDate - String!
  6. 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.
  7. features - Features!
    • Optional features

Visibility

ENUM
Enum Values
  1. PUBLIC
  2. UNLISTED
  3. PRIVATE

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!

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

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