Headers

• Commune-Version string(date)

  The contract version this request is written against, as a release date (YYYY-MM-DD). Omitting the header pins the request to the version that was current when the API key was issued, so an integration keeps working when a newer version ships. An unknown value answers 400 with invalid_version.

Path parameters

• user string Required

  The user's id or their username, with or without a leading @.

Query parameters

• fields string

  Comma separated allow list of top level properties to return on each object, so a client can trim a response it does not need in full. id and object are always returned. An unknown property name answers 400. Properties omitted by an operation, such as content on any article list, cannot be brought back with fields.

  A trimmed body is a subset of the schema this operation declares, and a property that schema marks required is absent when it was not asked for. That is the point of the parameter, so a client that validates responses against the schema either sends no fields or relaxes required.

Responses

• 200 application/json

  The user.

  Hide response attributes Show response attributes object

  • object string Required

    Always user.

    Value is user.

  • id string Required

    Stable identifier.

  • username string | null

    The unique handle the profile resolves on at /@{username}. Null for an account that has not finished signing up.

  • display_name string | null

    The name shown next to their messages and bylines.

  • avatar string(uri) | null

    Profile picture. Commune falls back to a generated avatar when the person never set one, so this is rarely null in practice.

• 400 application/json

  The request was malformed: an unknown query parameter, an unparseable cursor, an unknown expand path, or an unrecognised Commune-Version.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, rate_limited, or internal_error.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It is deliberately redundant with message, which names the same values in prose. The array is what a program branches on and the sentence is what a model reads, and a caller correcting a request has to be able to do it from this one response without opening a reference page.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is no parameter at fault and param is absent, and this carries the scopes that would have been accepted instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the reference page for this error code.

• 401 application/json

  No API key was presented, or the key is unknown, revoked or expired.

  All four answer identically, down to the wording. Saying that a key was revoked rather than never issued confirms to whoever is holding the string that it was once real, which a legitimate caller does not need and a thief should not get.

  Hide headers attribute Show headers attribute

  • WWW-Authenticate string

    The authentication scheme this API accepts. Always Bearer realm="Commune API"; there is no second scheme and no query-parameter fallback, because a credential that can travel in a URL ends up in access logs and referer headers.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, rate_limited, or internal_error.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It is deliberately redundant with message, which names the same values in prose. The array is what a program branches on and the sentence is what a model reads, and a caller correcting a request has to be able to do it from this one response without opening a reference page.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is no parameter at fault and param is absent, and this carries the scopes that would have been accepted instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the reference page for this error code.

• 404 application/json

  No such resource, or the key is not allowed to know that it exists. Commune answers 404 rather than 403 where distinguishing the two would leak the existence of private content.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, rate_limited, or internal_error.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It is deliberately redundant with message, which names the same values in prose. The array is what a program branches on and the sentence is what a model reads, and a caller correcting a request has to be able to do it from this one response without opening a reference page.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is no parameter at fault and param is absent, and this carries the scopes that would have been accepted instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the reference page for this error code.

• 429 application/json

  Too many requests. Back off and retry after the interval named by the Retry-After response header.

  Hide headers attribute Show headers attribute

  • Retry-After integer

    Seconds to wait before retrying.

    Minimum value is 1.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, rate_limited, or internal_error.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It is deliberately redundant with message, which names the same values in prose. The array is what a program branches on and the sentence is what a model reads, and a caller correcting a request has to be able to do it from this one response without opening a reference page.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is no parameter at fault and param is absent, and this carries the scopes that would have been accepted instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the reference page for this error code.

• 500 application/json

  Something failed inside Commune. The request may be retried.

  Hide response attribute Show response attribute object

  • error object Required

    Additional properties are NOT allowed.

    Hide error attributes Show error attributes object

    • code string Required

      The stable, machine readable reason a request failed. New codes may be added in a minor version, so treat an unrecognised code as a generic failure of its HTTP status class.

      Values are bad_request, invalid_version, unauthorized, forbidden, insufficient_scope, payment_required, not_found, conflict, unprocessable, rate_limited, or internal_error.

    • message string Required

      A human readable sentence describing what went wrong. Written for a developer reading a log, not for an end user. Do not branch on it, branch on code.

    • param string

      The query, path or body parameter the error is attributed to, when the error is attributable to exactly one. Absent otherwise.

    • allowed_values array[string]

      Everything param would have accepted, when what it accepts is a finite set. Absent when it is not: a cursor, an identifier or a numeric range has nothing to enumerate, and an empty array would read as "nothing is allowed".

      It is deliberately redundant with message, which names the same values in prose. The array is what a program branches on and the sentence is what a model reads, and a caller correcting a request has to be able to do it from this one response without opening a reference page.

      On an unknown parameter name rather than an unknown value, this carries the parameter names the operation does accept, since that is the set the caller has to pick from.

      On an insufficient_scope failure there is no parameter at fault and param is absent, and this carries the scopes that would have been accepted instead.

    • request_id string

      Identifier for this request, echoed in the Commune-Request-Id response header. Quote it in support requests.

    • docs_url string(uri)

      Link to the reference page for this error code.