sourcehut

meta.sr.ht API Documentation

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

Queries

auditLog

@access(scope:AUDIT_LOG, kind:RO)

Returns the audit log for the authenticated user.

Returns AuditLogCursor!

Arguments
  1. cursor - Cursor
Example Query 
query auditLog($cursor: Cursor) {
    auditLog(cursor: $cursor) {
        results {
            ...AuditLogEntry
        }
        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
        sshKeys {
            ...SSHKeyCursor
        }
        pgpKeys {
            ...PGPKeyCursor
        }
        paymentStatus
        paymentDue
        subscription {
            ...BillingSubscription
        }
        invoices {
            ...InvoiceCursor
        }
        billingAddress {
            ...BillingAddress
        }
        userType
        receivesPaidServices
        suspensionNotice
    }
}

myOauthGrant

Returns the current OAuth grant in use, if any

Returns OAuthGrant

Example Query 
query myOauthGrant {
    myOauthGrant {
        id
        client {
            ...OAuthClient
        }
        issued
        expires
        tokenHash
        grants
    }
}

oauthClientByID

@internal

Returns a specific OAuth client (by database ID)

Returns OAuthClient

Arguments
  1. id - Int!
Example Query 
query oauthClientByID($id: Int!) {
    oauthClientByID(id: $id) {
        id
        uuid
        redirectUrl
        name
        description
        url
        owner {
            ...Entity
        }
    }
}

oauthClientByUUID

@internal

Returns a specific OAuth client (by UUID)

Returns OAuthClient

Arguments
  1. uuid - String!
Example Query 
query oauthClientByUUID($uuid: String!) {
    oauthClientByUUID(uuid: $uuid) {
        id
        uuid
        redirectUrl
        name
        description
        url
        owner {
            ...Entity
        }
    }
}

oauthClients

@private

List of OAuth clients this user administrates

Returns [OAuthClient]!

Example Query 
query oauthClients {
    oauthClients {
        id
        uuid
        redirectUrl
        name
        description
        url
        owner {
            ...Entity
        }
    }
}

oauthGrants

@private

Returns OAuth grants issued for the authenticated user

Returns [OAuthGrant]!

Example Query 
query oauthGrants {
    oauthGrants {
        id
        client {
            ...OAuthClient
        }
        issued
        expires
        tokenHash
        grants
    }
}

personalAccessTokens

@private

Returns a list of personal OAuth tokens issued

Returns [OAuthPersonalToken]!

Example Query 
query personalAccessTokens {
    personalAccessTokens {
        id
        issued
        expires
        comment
        grants
    }
}

pgpKeyByFingerprint

@access(scope:PGP_KEYS, kind:RO)

Returns a specific PGP key by its fingerprint, in hexadecimal.

Returns PGPKey

Arguments
  1. fingerprint - String!
Example Query 
query pgpKeyByFingerprint($fingerprint: String!) {
    pgpKeyByFingerprint(fingerprint: $fingerprint) {
        id
        created
        user {
            ...User
        }
        key
        fingerprint
    }
}

product

Returns information about a subscription product available for purchase.

Returns Product

Arguments
  1. id - Int!
Example Query 
query product($id: Int!) {
    product(id: $id) {
        id
        name
        prices {
            ...ProductPrice
        }
        retired
    }
}

products

Returns a list of paid subscriptions available for purchase.

Returns [Product]!

Example Query 
query products {
    products {
        id
        name
        prices {
            ...ProductPrice
        }
        retired
    }
}

profileWebhook

Returns details of a user profile webhook subscription by its ID.

Returns WebhookSubscription

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

profileWebhooks

Returns a list of user profile 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 profileWebhooks($cursor: Cursor) {
    profileWebhooks(cursor: $cursor) {
        results {
            ...WebhookSubscription
        }
        cursor
    }
}

sshKeyByFingerprint

@access(scope:SSH_KEYS, kind:RO)

Returns a specific SSH key by its fingerprint, in hexadecimal

Returns SSHKey

Arguments
  1. fingerprint - String!
Example Query 
query sshKeyByFingerprint($fingerprint: String!) {
    sshKeyByFingerprint(fingerprint: $fingerprint) {
        id
        created
        lastUsed
        user {
            ...User
        }
        key
        fingerprint
        comment
        username
    }
}

sshKeyByFingerprintInternal

@anoninternal

Returns SSHKey

Arguments
  1. fingerprint - String!
Example Query 
query sshKeyByFingerprintInternal($fingerprint: String!) {
    sshKeyByFingerprintInternal(fingerprint: $fingerprint) {
        id
        created
        lastUsed
        user {
            ...User
        }
        key
        fingerprint
        comment
        username
    }
}

tokenRevocationStatus

@internal

Returns the revocation status of a given OAuth 2.0 token hash (SHA-512). If the token or client ID has been revoked, this returns true, and the key should not be trusted. Client ID is optional for personal access tokens.

Returns Boolean!

Arguments
  1. hash - String!
  2. clientId - String
Example Query 
query tokenRevocationStatus($hash: String!, $clientId: String) {
    tokenRevocationStatus(hash: $hash, clientId: $clientId) {
    }
}

user

@anoninternal

Returns a specific user by username

Returns User

Arguments
  1. username - String!
Example Query 
query user($username: String!) {
    user(username: $username) {
        id
        created
        updated
        canonicalName
        username
        email
        url
        location
        bio
        sshKeys {
            ...SSHKeyCursor
        }
        pgpKeys {
            ...PGPKeyCursor
        }
        paymentStatus
        paymentDue
        subscription {
            ...BillingSubscription
        }
        invoices {
            ...InvoiceCursor
        }
        billingAddress {
            ...BillingAddress
        }
        userType
        receivesPaidServices
        suspensionNotice
    }
}

userByEmail

@access(scope:PROFILE, kind:RO)

Returns User

Arguments
  1. email - String!
Example Query 
query userByEmail($email: String!) {
    userByEmail(email: $email) {
        id
        created
        updated
        canonicalName
        username
        email
        url
        location
        bio
        sshKeys {
            ...SSHKeyCursor
        }
        pgpKeys {
            ...PGPKeyCursor
        }
        paymentStatus
        paymentDue
        subscription {
            ...BillingSubscription
        }
        invoices {
            ...InvoiceCursor
        }
        billingAddress {
            ...BillingAddress
        }
        userType
        receivesPaidServices
        suspensionNotice
    }
}

userByID

@anoninternal

Returns a specific user by ID

Returns User

Arguments
  1. id - Int!
Example Query 
query userByID($id: Int!) {
    userByID(id: $id) {
        id
        created
        updated
        canonicalName
        username
        email
        url
        location
        bio
        sshKeys {
            ...SSHKeyCursor
        }
        pgpKeys {
            ...PGPKeyCursor
        }
        paymentStatus
        paymentDue
        subscription {
            ...BillingSubscription
        }
        invoices {
            ...InvoiceCursor
        }
        billingAddress {
            ...BillingAddress
        }
        userType
        receivesPaidServices
        suspensionNotice
    }
}

userByName

@access(scope:PROFILE, kind:RO)

Returns a specific user

Returns User

Arguments
  1. username - String!
Example Query 
query userByName($username: String!) {
    userByName(username: $username) {
        id
        created
        updated
        canonicalName
        username
        email
        url
        location
        bio
        sshKeys {
            ...SSHKeyCursor
        }
        pgpKeys {
            ...PGPKeyCursor
        }
        paymentStatus
        paymentDue
        subscription {
            ...BillingSubscription
        }
        invoices {
            ...InvoiceCursor
        }
        billingAddress {
            ...BillingAddress
        }
        userType
        receivesPaidServices
        suspensionNotice
    }
}

version

Returns API version information.

Returns Version!

Example Query 
query version {
    version {
        major
        minor
        patch
        deprecationDate
    }
}

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

billingTransfer

@admin

Transfers billing details from one user account to another, returning the target account.

Returns User!

Arguments
  1. from - String!
  2. to - String!
Example Query 
query billingTransfer($from: String!, $to: String!) {
    billingTransfer(from: $from, to: $to) {
        id
        created
        updated
        canonicalName
        username
        email
        url
        location
        bio
        sshKeys {
            ...SSHKeyCursor
        }
        pgpKeys {
            ...PGPKeyCursor
        }
        paymentStatus
        paymentDue
        subscription {
            ...BillingSubscription
        }
        invoices {
            ...InvoiceCursor
        }
        billingAddress {
            ...BillingAddress
        }
        userType
        receivesPaidServices
        suspensionNotice
    }
}

confirmEmailChange

@anoninternal

Confirm a user's change of email address

Returns User

Arguments
  1. token - String!
Example Query 
query confirmEmailChange($token: String!) {
    confirmEmailChange(token: $token) {
        id
        created
        updated
        canonicalName
        username
        email
        url
        location
        bio
        sshKeys {
            ...SSHKeyCursor
        }
        pgpKeys {
            ...PGPKeyCursor
        }
        paymentStatus
        paymentDue
        subscription {
            ...BillingSubscription
        }
        invoices {
            ...InvoiceCursor
        }
        billingAddress {
            ...BillingAddress
        }
        userType
        receivesPaidServices
        suspensionNotice
    }
}

confirmPasswordChange

@anoninternal

Confirm a user's password change

Returns User

Arguments
  1. token - String!
  2. newPassword - String!
Example Query 
query confirmPasswordChange($token: String!, $newPassword: String!) {
    confirmPasswordChange(token: $token, newPassword: $newPassword) {
        id
        created
        updated
        canonicalName
        username
        email
        url
        location
        bio
        sshKeys {
            ...SSHKeyCursor
        }
        pgpKeys {
            ...PGPKeyCursor
        }
        paymentStatus
        paymentDue
        subscription {
            ...BillingSubscription
        }
        invoices {
            ...InvoiceCursor
        }
        billingAddress {
            ...BillingAddress
        }
        userType
        receivesPaidServices
        suspensionNotice
    }
}

confirmRegistration

@anoninternal

Confirm an account registration email.

Returns User

Arguments
  1. token - String!
Example Query 
query confirmRegistration($token: String!) {
    confirmRegistration(token: $token) {
        id
        created
        updated
        canonicalName
        username
        email
        url
        location
        bio
        sshKeys {
            ...SSHKeyCursor
        }
        pgpKeys {
            ...PGPKeyCursor
        }
        paymentStatus
        paymentDue
        subscription {
            ...BillingSubscription
        }
        invoices {
            ...InvoiceCursor
        }
        billingAddress {
            ...BillingAddress
        }
        userType
        receivesPaidServices
        suspensionNotice
    }
}

createPGPKey

@access(scope:PGP_KEYS, kind:RW)

Returns PGPKey!

Arguments
  1. key - String!
Example Query 
query createPGPKey($key: String!) {
    createPGPKey(key: $key) {
        id
        created
        user {
            ...User
        }
        key
        fingerprint
    }
}

createProduct

@admin

Create a new paid product.

Returns Product!

Arguments
  1. name - String!
  2. prices - [ProductPriceInput]!
Example Query 
query createProduct($name: String!, $prices: [ProductPriceInput!]!) {
    createProduct(name: $name, prices: $prices) {
        id
        name
        prices {
            ...ProductPrice
        }
        retired
    }
}

createSSHKey

@access(scope:SSH_KEYS, kind:RW)

Returns SSHKey!

Arguments
  1. key - String!
Example Query 
query createSSHKey($key: String!) {
    createSSHKey(key: $key) {
        id
        created
        lastUsed
        user {
            ...User
        }
        key
        fingerprint
        comment
        username
    }
}

createWebhook

Creates a new user profile 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 - ProfileWebhookInput!
Example Query 
query createWebhook($config: ProfileWebhookInput!) {
    createWebhook(config: $config) {
        id
        events
        query
        url
        client {
            ...OAuthClient
        }
        deliveries {
            ...WebhookDeliveryCursor
        }
        sample
    }
}

deletePGPKey

@access(scope:PGP_KEYS, kind:RW)

Returns PGPKey

Arguments
  1. id - Int!
Example Query 
query deletePGPKey($id: Int!) {
    deletePGPKey(id: $id) {
        id
        created
        user {
            ...User
        }
        key
        fingerprint
    }
}

deleteSSHKey

@access(scope:SSH_KEYS, kind:RW)

Returns SSHKey

Arguments
  1. id - Int!
Example Query 
query deleteSSHKey($id: Int!) {
    deleteSSHKey(id: $id) {
        id
        created
        lastUsed
        user {
            ...User
        }
        key
        fingerprint
        comment
        username
    }
}

deleteUser

@internal

Deletes the authenticated user's account.

Returns Int!

Arguments
  1. reserve - Boolean!
Example Query 
query deleteUser($reserve: Boolean!) {
    deleteUser(reserve: $reserve) {
    }
}

deleteWebhook

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

issueAuthorizationCode

@internal

Issues an OAuth 2.0 authorization code. Used after the user has consented to the access grant request.

Returns String!

Arguments
  1. clientUUID - String!
  2. grants - String!
Example Query 
query issueAuthorizationCode($clientUUID: String!, $grants: String!) {
    issueAuthorizationCode(clientUUID: $clientUUID, grants: $grants) {
    }
}

issueOAuthGrant

@internal

Completes the OAuth 2.0 grant process and issues an OAuth token for a specific OAuth client.

Returns OAuthGrantRegistration

Arguments
  1. authorization - String!
  2. clientUUID - String
  3. clientSecret - String!
  4. redirectUri - String
Example Query 
query issueOAuthGrant($authorization: String!, $clientUUID: String, $clientSecret: String!, $redirectUri: String) {
    issueOAuthGrant(authorization: $authorization, clientUUID: $clientUUID, clientSecret: $clientSecret, redirectUri: $redirectUri) {
        grant {
            ...OAuthGrant
        }
        grants
        secret
        refreshToken
    }
}

issuePersonalAccessToken

@internal

Issues an OAuth personal access token.

Returns OAuthPersonalTokenRegistration!

Arguments
  1. grants - String
  2. comment - String
Example Query 
query issuePersonalAccessToken($grants: String, $comment: String) {
    issuePersonalAccessToken(grants: $grants, comment: $comment) {
        token {
            ...OAuthPersonalToken
        }
        secret
    }
}

refreshOAuthGrant

@internal

Refreshes an existing OAuth 2.0 grant. This invalidates the previous grant and returns a new one.

Returns OAuthGrantRegistration

Arguments
  1. refreshToken - String!
  2. clientUUID - String!
  3. clientSecret - String!
  4. grants - String
Example Query 
query refreshOAuthGrant($refreshToken: String!, $clientUUID: String!, $clientSecret: String!, $grants: String) {
    refreshOAuthGrant(refreshToken: $refreshToken, clientUUID: $clientUUID, clientSecret: $clientSecret, grants: $grants) {
        grant {
            ...OAuthGrant
        }
        grants
        secret
        refreshToken
    }
}

registerAccount

@anoninternal

Registers a new account.

Returns User

Arguments
  1. email - String!
  2. username - String!
  3. password - String!
  4. pgpKey - String
Example Query 
query registerAccount($email: String!, $username: String!, $password: String!, $pgpKey: String) {
    registerAccount(email: $email, username: $username, password: $password, pgpKey: $pgpKey) {
        id
        created
        updated
        canonicalName
        username
        email
        url
        location
        bio
        sshKeys {
            ...SSHKeyCursor
        }
        pgpKeys {
            ...PGPKeyCursor
        }
        paymentStatus
        paymentDue
        subscription {
            ...BillingSubscription
        }
        invoices {
            ...InvoiceCursor
        }
        billingAddress {
            ...BillingAddress
        }
        userType
        receivesPaidServices
        suspensionNotice
    }
}

registerOAuthClient

@internal

Registers an OAuth client. Only OAuth 2.0 confidental clients are supported.

Returns OAuthClientRegistration!

Arguments
  1. redirectUri - String!
  2. clientName - String!
  3. clientDescription - String
  4. clientUrl - String
Example Query 
query registerOAuthClient($redirectUri: String!, $clientName: String!, $clientDescription: String, $clientUrl: String) {
    registerOAuthClient(redirectUri: $redirectUri, clientName: $clientName, clientDescription: $clientDescription, clientUrl: $clientUrl) {
        client {
            ...OAuthClient
        }
        secret
    }
}

resetPassword

@anoninternal

Requests a password reset. The return value is meaningless.

Returns Int

Arguments
  1. email - String!
Example Query 
query resetPassword($email: String!) {
    resetPassword(email: $email) {
    }
}

retireProduct

@admin

Retires a paid product.

Returns Product

Arguments
  1. id - Int!
Example Query 
query retireProduct($id: Int!) {
    retireProduct(id: $id) {
        id
        name
        prices {
            ...ProductPrice
        }
        retired
    }
}

revokeOAuthClient

@internal

Revokes this OAuth client, revoking all tokens for it and preventing future use.

Returns OAuthClient

Arguments
  1. uuid - String!
Example Query 
query revokeOAuthClient($uuid: String!) {
    revokeOAuthClient(uuid: $uuid) {
        id
        uuid
        redirectUrl
        name
        description
        url
        owner {
            ...Entity
        }
    }
}

revokeOAuthGrant

@internal

Revokes a specific OAuth grant.

Returns OAuthGrant

Arguments
  1. hash - String!
Example Query 
query revokeOAuthGrant($hash: String!) {
    revokeOAuthGrant(hash: $hash) {
        id
        client {
            ...OAuthClient
        }
        issued
        expires
        tokenHash
        grants
    }
}

revokePersonalAccessToken

@internal

Revokes a personal access token.

Returns OAuthPersonalToken

Arguments
  1. id - Int!
Example Query 
query revokePersonalAccessToken($id: Int!) {
    revokePersonalAccessToken(id: $id) {
        id
        issued
        expires
        comment
        grants
    }
}

sendEmail

@anoninternal

Send a notification email.

The 'address' parameter must be a single RFC 5322 address (e.g. "Barry Gibbs bg@example.com", or "bg@example.com"). The 'message' parameter must be a RFC 5322 compliant Internet message with the special requirement that it must not contain any recipients (i.e. no 'To', 'Cc', or 'Bcc' header).

The message will be signed with the site key. If the address is that of a registered user it will be encrypted according to the user's privacy settings.

Returns Boolean!

Arguments
  1. address - String!
  2. message - String!
Example Query 
query sendEmail($address: String!, $message: String!) {
    sendEmail(address: $address, message: $message) {
    }
}

subsidizeUser

@admin

Grants free service to the given user ID until the provided expiration date.

Returns User!

Arguments
  1. userID - Int!
  2. until - Time!
Example Query 
query subsidizeUser($userID: Int!, $until: Time!) {
    subsidizeUser(userID: $userID, until: $until) {
        id
        created
        updated
        canonicalName
        username
        email
        url
        location
        bio
        sshKeys {
            ...SSHKeyCursor
        }
        pgpKeys {
            ...PGPKeyCursor
        }
        paymentStatus
        paymentDue
        subscription {
            ...BillingSubscription
        }
        invoices {
            ...InvoiceCursor
        }
        billingAddress {
            ...BillingAddress
        }
        userType
        receivesPaidServices
        suspensionNotice
    }
}

updateBillingAddress

@access(scope:BILLING, kind:RW)

Update the authenticated user's billing address.

Returns BillingAddress!

Arguments
  1. input - BillingAddressInput!
Example Query 
query updateBillingAddress($input: BillingAddressInput!) {
    updateBillingAddress(input: $input) {
        fullName
        businessName
        address1
        address2
        city
        region
        postcode
        country
        vat
    }
}

updateSSHKeyLastUsed

@access(scope:SSH_KEYS, kind:RO)
@internal

Causes the "last used" time of this SSH key to be set to the current time.

Returns SSHKey!

Arguments
  1. id - Int!
Example Query 
query updateSSHKeyLastUsed($id: Int!) {
    updateSSHKeyLastUsed(id: $id) {
        id
        created
        lastUsed
        user {
            ...User
        }
        key
        fingerprint
        comment
        username
    }
}

updateUser

@access(scope:PROFILE, kind:RW)

Returns User!

Arguments
  1. input - UserInput
Example Query 
query updateUser($input: UserInput) {
    updateUser(input: $input) {
        id
        created
        updated
        canonicalName
        username
        email
        url
        location
        bio
        sshKeys {
            ...SSHKeyCursor
        }
        pgpKeys {
            ...PGPKeyCursor
        }
        paymentStatus
        paymentDue
        subscription {
            ...BillingSubscription
        }
        invoices {
            ...InvoiceCursor
        }
        billingAddress {
            ...BillingAddress
        }
        userType
        receivesPaidServices
        suspensionNotice
    }
}

Definitions

AccessKind

Enum Values
  1. RO
  2. RW

AccessScope

Enum Values
  1. AUDIT_LOG
  2. BILLING
  3. PGP_KEYS
  4. SSH_KEYS
  5. PROFILE

AuditLogCursor

A cursor for enumerating a list of audit log 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 - [AuditLogEntry]!
  2. cursor - Cursor

AuditLogEntry

Fields
  1. id - Int!
  2. created - Time!
  3. ipAddress - String!
  4. eventType - String!
  5. details - String

BillingAddress

Billing address for invoicing.

Fields
  1. fullName - String
  2. businessName - String
  3. address1 - String
  4. address2 - String
  5. city - String
  6. region - String
  7. postcode - String
  8. country - String
    • ISO 3166 two-letter country code
  9. vat - String
    • Value-added tax number (EU)

BillingAddressInput

All fields are optional. If a field is omitted, it is unchanged. If a field is null, it is set to null.

Fields
  1. fullName - String
  2. businessName - String
  3. address1 - String
  4. address2 - String
  5. city - String
  6. region - String
  7. postcode - String
  8. country - String
    • ISO 3166 two-letter country code
  9. vat - String
    • Value-added tax number (EU)

BillingSubscription

Fields
  1. id - Int!
  2. user - User!
  3. created - Time!
  4. updated - Time!
  5. status - SubscriptionStatus!
  6. autorenew - Boolean!
    • If true, payment is automatically renewed when term ellapses.
  7. currency - Currency!
  8. interval - PaymentInterval!
  9. product - Product!
    • Selected product associated with this subscription.
  10. price - ProductPrice!
    • Shortcut to get the applicable price point for this subscription's product ID and applicable currency
  11. subtotal - Int!
    • Total price, not including applicable taxes, in the smallest denomination of the currency, e.g. cents USD.

Boolean

The Boolean scalar type represents true or false.

Currency

Enum Values
  1. EUR
  2. USD

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.

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.

Invoice

Fields
  1. id - Int!
  2. invoiceNo - String!
  3. issued - Time!
  4. entity - Entity!
  5. product - Product!
  6. serviceStart - Time!
    • Start of service period for which this invoice applies
  7. serviceEnd - Time!
    • End of service period for which this invoice applies
  8. currency - Currency!
  9. total - Int!
    • Amount charged denoted in the smallest denomination of the applicable currency, e.g. cents USD.

InvoiceCursor

A cursor for enumerating a list of invoices

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

OAuthClient

Fields
  1. id - Int!
  2. uuid - String!
  3. redirectUrl - String!
  4. name - String!
  5. description - String
  6. url - String
  7. owner - Entity!

OAuthClientRegistration

Fields
  1. client - OAuthClient!
  2. secret - String!

OAuthGrant

Fields
  1. id - Int!
  2. client - OAuthClient!
  3. issued - Time!
  4. expires - Time!
  5. tokenHash - String!
  6. grants - String

OAuthGrantRegistration

Fields
  1. grant - OAuthGrant!
  2. grants - String!
  3. secret - String!
  4. refreshToken - String!

OAuthPersonalToken

Fields
  1. id - Int!
  2. issued - Time!
  3. expires - Time!
  4. comment - String
  5. grants - String

OAuthPersonalTokenRegistration

Fields
  1. token - OAuthPersonalToken!
  2. secret - String!

PGPKey

Fields
  1. id - Int!
  2. created - Time!
  3. user - User!
  4. key - String!
  5. fingerprint - String!

PGPKeyCursor

A cursor for enumerating a list of PGP keys

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

PGPKeyEvent

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

PaymentInterval

Enum Values
  1. MONTHLY
  2. ANNUALLY

PaymentStatus

Enum Values
  1. UNPAID
    • User does not pay for their account
  2. CURRENT
    • User is paid and their payment is current
  3. DELINQUENT
    • User's payment has lapsed
  4. SUBSIDIZED
    • User's paid services are subsidized
  5. FREE
    • User receives paid services for free

Product

A paid product available for purchase.

Fields
  1. id - Int!
  2. name - String!
  3. prices - [ProductPrice]!
  4. retired - Boolean!

ProductPrice

Price point for a product in a given currency.

Fields
  1. currency - Currency!
    • Applicable currency for this price
  2. amount - Int!
    • Price in the smallest denomination of the currency, e.g. cents USD. Does not include any applicable taxes.

ProductPriceInput

Fields
  1. currency - Currency!
  2. amount - Int!

ProfileUpdateEvent

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

ProfileWebhookInput

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

ProfileWebhookSubscription

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

SSHKey

Fields
  1. id - Int!
  2. created - Time!
  3. lastUsed - Time
  4. user - User!
  5. key - String!
  6. fingerprint - String!
  7. comment - String
  8. username - String!

SSHKeyCursor

A cursor for enumerating a list of SSH keys

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

SSHKeyEvent

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

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.

SubscriptionStatus

Enum Values
  1. PENDING
    • This subscription is pending and will become active once the first payment is successfully recieved.
  2. SETTLEMENT
    • This subscription is paid but the payment has not settled. Paid services are available while awaiting settlement.
  3. ACTIVE
    • This is the user's active subscription.
  4. INACTIVE
    • This subscription has been cancelled and the service term is complete.

Time

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. sshKeys - SSHKeyCursor!
  11. pgpKeys - PGPKeyCursor!
  12. paymentStatus - PaymentStatus!
    • User's current payment status. Only available if authenticated as this user.
  13. paymentDue - Time
    • Date at which next payment is due. Only available if authenticated as this user.
  14. subscription - BillingSubscription
    • Details about the user's current paid subscription. Only available if authenticated as this user.
  15. invoices - InvoiceCursor!
    • Returns invoices for this user. Only available if authenticated as this user.
  16. billingAddress - BillingAddress
    • User's billing address, if applicable, for invoicing.
  17. userType - UserType!
    • Internal user type (e.g. is admin)
  18. receivesPaidServices - Boolean!
    • Returns true if this user should have access to paid services.
  19. suspensionNotice - String
    • Notice to provide to a suspended account

UserInput

Omit these fields to leave them unchanged, or set them to null to clear their value.

Fields
  1. url - String
  2. location - String
  3. bio - String
  4. email - String
    • Note: changing the user's email address will not take effect immediately; the user is sent an email to confirm the change first.

UserType

Enum Values
  1. PENDING
  2. USER
  3. ADMIN
  4. SUSPENDED

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.

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. PROFILE_UPDATE
    • Used for user profile webhooks
  2. PGP_KEY_ADDED
  3. PGP_KEY_REMOVED
  4. SSH_KEY_ADDED
  5. SSH_KEY_REMOVED

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!

@admin

Used to decorate fields which are only available to admin accounts.

@anoninternal

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

@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

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.