Create a project

API v3 is in preview

Endpoints and response shapes can change before general availability. API v2 is unchanged.

POST https://app.honeybadger.io/v3/projects

Required scope projects:create

Creates a new project in the account.

Example request

curl -X POST "https://app.honeybadger.io/v3/projects" \
  -H "Authorization: Bearer $HONEYBADGER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Billing API"
}'

Request body

Field	Type	Description
name required	string	Project name.
resolve_errors_on_deploy	boolean | null	Resolve every open fault when a deploy is recorded. Null resets it to true. Default: true.
disable_public_links	boolean | null	Disallow shareable public fault links. Null resets it to false. Default: false.
language	string | null	Primary language, used to format backtraces. Null clears it.
user_url	string | null	Template for linking a fault's affected user into your own system. [user_id] and [user_email] are substituted. Null clears it.
source_url	string | null	Template for linking a backtrace line to your source host. [file] and [line] are substituted. Null clears it.
user_search_field	string | null	Context key identifying the affected user, for when it is not in the default context.user_email or context.user_id. Null clears it.
asana_workspace_id	string | null	Asana workspace used by the project's Asana integration. Null clears it.
customer_throttle	integer | null	Notices accepted per minute before throttling kicks in. Null clears it.
purge_days	integer | null	Days to retain notices. Changing it requires custom retention on the account; without it, only the current value (on create, the default) is accepted. Null clears it.
disable_email_notifications	boolean	Create-only. Members added with the project get email notifications switched off. Not stored or returned.
team_id	string	Puts the new project in this team. Create-only: afterwards the team's project_ids owns membership. Including it requires team:write in addition to the operation's project scope, and the user must be allowed to manage the team. Without team:write the entire request is rejected with 403 insufficient_scope; no other fields are saved.

Responses

1

201 Project created

Example payload

{
  "data": {
    "id": "Xk9mZp",
    "account_id": "Ab3kL9",
    "name": "My Rails App",
    "active": true,
    "disable_public_links": true,
    "environments": [
      "production",
      "staging",
      "development"
    ],
    "resolve_errors_on_deploy": true,
    "user_url": "https://admin.example.com/users/[user_id]",
    "source_url": "https://github.com/acme/app/blob/main/[file]#L[line]",
    "user_search_field": "context.account_id",
    "asana_workspace_id": null,
    "customer_throttle": 0,
    "language": "Ruby",
    "fault_count": 128,
    "unresolved_fault_count": 12,
    "last_notice_at": "2026-01-01T00:00:00Z",
    "earliest_notice_at": "2026-01-01T00:00:00Z",
    "purge_days": 90,
    "created_at": "2026-01-01T00:00:00Z",
    "links": {
      "web": "https://app.honeybadger.io/projects/Xk9mZp"
    }
  },
  "meta": {
    "request_id": "6f1c2b0e-8d4a-4f6e-9b2a-3c5d7e9f1a2b"
  }
}

Response schema24

Field	Type	Description
data required	object	A Honeybadger project: one application or service. Errors, Insights data, uptime sites, check-ins, deploys and integrations all belong to a project.
data.id required	string
data.account_id required	string	ID of the account this project belongs to.
data.name required	string	Project name.
data.active required	boolean	Whether the project is active.
data.disable_public_links required	boolean	Whether public error links are disabled.
data.environments required	array<string>	List of environment names seen in this project.
data.resolve_errors_on_deploy required	boolean	Whether recording a deploy resolves every open fault.
data.user_url required	string | null	Template linking a fault's affected user into your own system. [user_id] and [user_email] are substituted.
data.source_url required	string | null	Template linking a backtrace line to your source host. [file] and [line] are substituted.
data.user_search_field required	string | null	Context key identifying the affected user, when it is not in the default context.user_email or context.user_id.
data.asana_workspace_id required	string | null	Asana workspace used by the project's Asana integration.
data.customer_throttle required	integer | null	Notices accepted per minute before throttling kicks in.
data.language required	string | null	Primary programming language.
data.fault_count required	integer	Total number of faults (errors) in this project.
data.unresolved_fault_count required	integer	Number of unresolved faults.
data.last_notice_at required	date-time | null	When the last error was received.
data.earliest_notice_at required	date-time | null	The start of the retention window: now minus the project's purge_days (or the account's retention when unset), at most 180 days. Computed on each read, so it moves forward with the clock.
data.purge_days required	integer | null	Data retention period in days.
data.created_at required	date-time	When the project was created.
data.links required	object	Links into the Honeybadger web UI.
data.links.web required	uri	The resource's page in the Honeybadger web UI, as an absolute URL. Resources without a page, such as outages and deploys, don't have links. For a project provisioned through Heroku, error, notice and comment links go through Heroku's single sign-on.
meta	object
meta.request_id	string	Unique identifier for the request, for correlating with support.

Errors

6

400 Bad Request

A query parameter is malformed or outside its allowed values. error.details names the parameter.

Example payload

{
  "error": {
    "code": "invalid_parameter",
    "message": "unmapped must be true or false",
    "details": [
      {
        "field": "unmapped",
        "message": "must be true or false"
      }
    ]
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
error required	object
error.code required	string	Machine-readable code. Branch on this, not the message. Allowed values: unauthorized, unsupported_auth_scheme, credential_in_query, access_denied, insufficient_scope, requires_user_token, project_restricted, account_inactive, account_parked, feature_unavailable, not_found, validation_error, delete_failed, limit_reached, rate_limit_exceeded, concurrent_request, streams_provisioning, ingestion_key_not_accepted, maintenance_mode, invalid_parameter, forbidden_attributes, service_unavailable, ambiguous_account, fault_merged.
error.message required	string	Human-readable explanation.
error.details	array<object> | object	A list of {field, message} on validation_error and invalid_parameter, and on feature_unavailable or limit_reached when one field caused the refusal; {required_scope, token_scopes} on insufficient_scope; {merged_into, location} on fault_merged. Absent when there's nothing to add.
meta	object
meta.request_id	string	Unique identifier for the request, for correlating with support.

401 Unauthorized

The credential is missing, invalid, expired or revoked (unauthorized), or was sent in a way v3 doesn’t accept (see the examples).

Example payload: unauthorized (Missing, malformed, expired or revoked credential)

{
  "error": {
    "code": "unauthorized",
    "message": "Access denied"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: unsupported_auth_scheme (Sent as HTTP basic, which v3 does not accept)

{
  "error": {
    "code": "unsupported_auth_scheme",
    "message": "Send the credential as `Authorization: Bearer <token>`; v3 does not accept HTTP basic"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: credential_in_query (Sent as the `auth_token` query parameter)

{
  "error": {
    "code": "credential_in_query",
    "message": "Credentials must be sent in the Authorization header"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
error required	object
error.code required	string	Machine-readable code. Branch on this, not the message. Allowed values: unauthorized, unsupported_auth_scheme, credential_in_query, access_denied, insufficient_scope, requires_user_token, project_restricted, account_inactive, account_parked, feature_unavailable, not_found, validation_error, delete_failed, limit_reached, rate_limit_exceeded, concurrent_request, streams_provisioning, ingestion_key_not_accepted, maintenance_mode, invalid_parameter, forbidden_attributes, service_unavailable, ambiguous_account, fault_merged.
error.message required	string	Human-readable explanation.
error.details	array<object> | object	A list of {field, message} on validation_error and invalid_parameter, and on feature_unavailable or limit_reached when one field caused the refusal; {required_scope, token_scopes} on insufficient_scope; {merged_into, location} on fault_merged. Absent when there's nothing to add.
meta	object
meta.request_id	string	Unique identifier for the request, for correlating with support.

403 Forbidden

The credential isn’t allowed to do this. error.code says why. An account or project the credential doesn’t cover is 404 not_found, not 403.

Example payload: access_denied (The credential isn't allowed to do this to this record)

{
  "error": {
    "code": "access_denied",
    "message": "Access denied"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: insufficient_scope (The credential lacks the permission this endpoint requires)

{
  "error": {
    "code": "insufficient_scope",
    "message": "Insufficient scope",
    "details": {
      "required_scope": "faults:write",
      "token_scopes": [
        "faults:read",
        "insights:read"
      ]
    }
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: requires_user_token (The endpoint records who acted, and an account token has nobody)

{
  "error": {
    "code": "requires_user_token",
    "message": "This endpoint records the person who acted, so it requires a user credential rather than an account token"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: project_restricted (A project-restricted credential cannot create a project)

{
  "error": {
    "code": "project_restricted",
    "message": "Project-restricted tokens cannot create projects"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
error required	object
error.code required	string	Machine-readable code. Branch on this, not the message. Allowed values: unauthorized, unsupported_auth_scheme, credential_in_query, access_denied, insufficient_scope, requires_user_token, project_restricted, account_inactive, account_parked, feature_unavailable, not_found, validation_error, delete_failed, limit_reached, rate_limit_exceeded, concurrent_request, streams_provisioning, ingestion_key_not_accepted, maintenance_mode, invalid_parameter, forbidden_attributes, service_unavailable, ambiguous_account, fault_merged.
error.message required	string	Human-readable explanation.
error.details	array<object> | object	A list of {field, message} on validation_error and invalid_parameter, and on feature_unavailable or limit_reached when one field caused the refusal; {required_scope, token_scopes} on insufficient_scope; {merged_into, location} on fault_merged. Absent when there's nothing to add.
meta	object
meta.request_id	string	Unique identifier for the request, for correlating with support.

404 Not Found

Resource not found

Example payload

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
error required	object
error.code required	string	Machine-readable code. Branch on this, not the message. Allowed values: unauthorized, unsupported_auth_scheme, credential_in_query, access_denied, insufficient_scope, requires_user_token, project_restricted, account_inactive, account_parked, feature_unavailable, not_found, validation_error, delete_failed, limit_reached, rate_limit_exceeded, concurrent_request, streams_provisioning, ingestion_key_not_accepted, maintenance_mode, invalid_parameter, forbidden_attributes, service_unavailable, ambiguous_account, fault_merged.
error.message required	string	Human-readable explanation.
error.details	array<object> | object	A list of {field, message} on validation_error and invalid_parameter, and on feature_unavailable or limit_reached when one field caused the refusal; {required_scope, token_scopes} on insufficient_scope; {merged_into, location} on fault_merged. Absent when there's nothing to add.
meta	object
meta.request_id	string	Unique identifier for the request, for correlating with support.

422 Unprocessable Content

Validation error

Example payload

{
  "error": {
    "code": "validation_error",
    "message": "Name can't be blank",
    "details": [
      {
        "field": "name",
        "message": "can't be blank"
      }
    ]
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
error required	object
error.code required	string	Machine-readable code. Branch on this, not the message. Allowed values: unauthorized, unsupported_auth_scheme, credential_in_query, access_denied, insufficient_scope, requires_user_token, project_restricted, account_inactive, account_parked, feature_unavailable, not_found, validation_error, delete_failed, limit_reached, rate_limit_exceeded, concurrent_request, streams_provisioning, ingestion_key_not_accepted, maintenance_mode, invalid_parameter, forbidden_attributes, service_unavailable, ambiguous_account, fault_merged.
error.message required	string	Human-readable explanation.
error.details	array<object> | object	A list of {field, message} on validation_error and invalid_parameter, and on feature_unavailable or limit_reached when one field caused the refusal; {required_scope, token_scopes} on insufficient_scope; {merged_into, location} on fault_merged. Absent when there's nothing to add.
meta	object
meta.request_id	string	Unique identifier for the request, for correlating with support.

429 Too Many Requests

Another project is being created in this account at the same moment (concurrent_request), or the rate limit is exceeded (rate_limit_exceeded). Nothing was created. Wait Retry-After seconds and retry.

Example payload

{
  "error": {
    "code": "concurrent_request",
    "message": "Another project is being created in this account; retry shortly"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
error required	object
error.code required	string	Machine-readable code. Branch on this, not the message. Allowed values: unauthorized, unsupported_auth_scheme, credential_in_query, access_denied, insufficient_scope, requires_user_token, project_restricted, account_inactive, account_parked, feature_unavailable, not_found, validation_error, delete_failed, limit_reached, rate_limit_exceeded, concurrent_request, streams_provisioning, ingestion_key_not_accepted, maintenance_mode, invalid_parameter, forbidden_attributes, service_unavailable, ambiguous_account, fault_merged.
error.message required	string	Human-readable explanation.
error.details	array<object> | object	A list of {field, message} on validation_error and invalid_parameter, and on feature_unavailable or limit_reached when one field caused the refusal; {required_scope, token_scopes} on insufficient_scope; {merged_into, location} on fault_merged. Absent when there's nothing to add.
meta	object
meta.request_id	string	Unique identifier for the request, for correlating with support.