API Reference

API Reference

The API uses GraphQL. Endpoint: https://api.htoprc.dev/api/graphql

Queries

configs

Fetch paginated configs with filtering and sorting.

query {
  configs(
    page: 1
    limit: 20
    sort: SCORE_DESC
    minScore: 5
    search: "colorful"
  ) {
    nodes {
      id
      slug
      title
      content
      score
      likesCount
      createdAt
    }
    totalCount
    pageInfo {
      page
      totalPages
      hasNextPage
    }
  }
}

Sort options: SCORE_DESC, SCORE_ASC, LIKES_DESC, LIKES_ASC, DATE_DESC, DATE_ASC

config

Fetch a single config by ID or slug.

query {
  config(slug: "my-config-abc123") {
    id
    slug
    title
    content
    score
    likesCount
    sourceType
    sourceUrl
    comments {
      id
      content
      author { username }
    }
  }
}

recentConfigs

Fetch recently added configs.

query {
  recentConfigs(limit: 6) {
    id
    slug
    title
    score
  }
}

Mutations

uploadConfig

Upload a new config (requires authentication).

mutation {
  uploadConfig(input: {
    title: "My Config"
    content: "htop_version=3.3.0\ncolor_scheme=5"
    userId: "user_123"
  }) {
    id
    slug
    status
  }
}

toggleLike

Like or unlike a config.

mutation {
  toggleLike(configId: "config_id", userId: "user_id") {
    liked
    likesCount
  }
}

addComment

Add a comment to a config.

mutation {
  addComment(
    configId: "config_id"
    content: "Great config!"
    userId: "user_id"
  ) {
    id
    content
    createdAt
  }
}

forkConfig

Fork an existing config.

mutation {
  forkConfig(
    id: "original_config_id"
    title: "My Fork"
    userId: "user_id"
  ) {
    id
    slug
    forkedFromId
  }
}

Rate Limits

Action	Limit
Upload	10/day
Like	100/day
Report	10/day

Authentication

Requests requiring authentication must include the user ID from Clerk.

The API validates user identity through the Clerk integration.