API reference

Update insight

PATCH /insights/{insight}. Parameters, permissions, request and response schemas.

PATCH /insights/{insight}

Update insight. Requires the REST write token ability. The bearer token selects the Team; a supplied team_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402.

Authentication

Use a team API key as Authorization: Bearer YOUR_API_KEY. The token ability and the user’s role must both allow this operation. See authentication.

{
  "ability": "write",
  "team": "Token-bound Team",
  "authorization": "Additional role, entity-policy and plan requirements vary by operation.",
  "billing": "Blocked billing mode rejects writes with 402."
}

Parameters

NameLocationRequiredDescription
insightpathYesThe insight ID

insight

{
  "type": "integer",
  "minimum": 1
}

Request body

The request body is optional.

application/json

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 255
    },
    "source": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 255
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 65535
    },
    "project_id": {
      "type": "integer"
    },
    "research_collection_id": {
      "type": [
        "integer",
        "null"
      ]
    },
    "user_id": {
      "type": [
        "integer",
        "null"
      ]
    },
    "insight_label_id": {
      "type": [
        "integer",
        "null"
      ]
    },
    "audience_ids": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": [
          "integer",
          "null"
        ]
      }
    },
    "experiment_ids": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": [
          "integer",
          "null"
        ]
      }
    },
    "idea_ids": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": [
          "integer",
          "null"
        ]
      }
    },
    "observation_ids": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": [
          "integer",
          "null"
        ]
      }
    },
    "learning_ids": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": [
          "integer",
          "null"
        ]
      }
    },
    "page_ids": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": [
          "integer",
          "null"
        ]
      }
    },
    "screen_annotations": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": [
          "integer",
          "null"
        ]
      }
    }
  },
  "title": "UpdateInsightRequest"
}
{
  "name": "Checkout delivery estimate",
  "description": null,
  "project_id": 101
}

Example request

curl --request PATCH 'https://api.example.test/api/insights/1' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Checkout delivery estimate","description":null,"project_id":101}'

Examples use fictional data. Replace resource IDs and the API host with your environment’s values.

Responses

200

InsightResource

Content type: application/json.

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "custom_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "numbering_scheme_id": {
          "type": [
            "integer",
            "null"
          ]
        },
        "custom_id_number": {
          "type": [
            "integer",
            "null"
          ]
        },
        "import_source": {
          "type": [
            "string",
            "null"
          ]
        },
        "import_source_ref": {
          "type": [
            "string",
            "null"
          ]
        },
        "import_source_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "data_import_id": {
          "type": [
            "integer",
            "null"
          ]
        },
        "imported_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "project_id": {
          "type": [
            "integer",
            "null"
          ]
        },
        "research_collection_id": {
          "type": [
            "integer",
            "null"
          ]
        },
        "insight_label_id": {
          "type": [
            "integer",
            "null"
          ]
        },
        "user_id": {
          "type": [
            "integer",
            "null"
          ]
        },
        "source": {
          "type": [
            "string",
            "null"
          ]
        },
        "source_id": {
          "type": [
            "integer",
            "null"
          ]
        },
        "source_item_key": {
          "type": [
            "string",
            "null"
          ]
        },
        "source_label": {
          "type": [
            "string",
            "null"
          ]
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "created_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "updated_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "deleted_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "has_ideas": {
          "type": "boolean"
        }
      },
      "required": [
        "id",
        "custom_id",
        "numbering_scheme_id",
        "custom_id_number",
        "import_source",
        "import_source_ref",
        "import_source_id",
        "data_import_id",
        "imported_at",
        "project_id",
        "research_collection_id",
        "insight_label_id",
        "user_id",
        "source",
        "source_id",
        "source_item_key",
        "source_label",
        "name",
        "description",
        "created_at",
        "updated_at",
        "deleted_at",
        "has_ideas"
      ],
      "title": "InsightResource"
    }
  },
  "required": [
    "data"
  ]
}
{
  "data": {
    "id": 101,
    "custom_id": null,
    "numbering_scheme_id": null,
    "custom_id_number": null,
    "import_source": null,
    "import_source_ref": null,
    "import_source_id": null,
    "data_import_id": null,
    "imported_at": null,
    "project_id": null,
    "research_collection_id": null,
    "insight_label_id": null,
    "user_id": null,
    "source": null,
    "source_id": null,
    "source_item_key": null,
    "source_label": null,
    "name": null,
    "description": null,
    "created_at": null,
    "updated_at": null,
    "deleted_at": null,
    "has_ideas": true
  }
}

401

Unauthenticated

Content type: application/json.

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "Error overview."
    }
  },
  "required": [
    "message"
  ]
}
{
  "message": "The request could not be completed."
}

402

The Team is in read-only billing mode.

Content type: application/json.

{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "const": "subscription_required"
    },
    "mode": {
      "type": "string",
      "const": "blocked"
    },
    "message": {
      "type": "string",
      "example": "Your team is in read-only mode. Update billing to make changes."
    },
    "grace_period_ends_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    }
  },
  "required": [
    "error",
    "mode",
    "message",
    "grace_period_ends_at"
  ]
}
{
  "error": "subscription_required",
  "mode": "blocked",
  "message": "Your team is in read-only mode. Update billing to make changes.",
  "grace_period_ends_at": null
}

403

Authorization error

Content type: application/json.

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "Error overview."
    }
  },
  "required": [
    "message"
  ]
}
{
  "message": "The request could not be completed."
}

404

Not found

Content type: application/json.

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "Error overview."
    }
  },
  "required": [
    "message"
  ]
}
{
  "message": "The request could not be completed."
}

422

Validation error

Content type: application/json.

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "Errors overview."
    },
    "errors": {
      "type": "object",
      "description": "A detailed description of each field that failed validation.",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "message",
    "errors"
  ]
}
{
  "message": "The request could not be completed.",
  "errors": {
    "name": [
      "The name field is required."
    ]
  }
}

429

Rate limit exceeded. Honor Retry-After before retrying.

Response headers:

{
  "Retry-After": {
    "description": "Seconds before retrying.",
    "schema": {
      "type": "integer"
    }
  }
}

Content type: application/json.

{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "example": "Too Many Attempts."
    }
  },
  "required": [
    "message"
  ]
}
{
  "message": "Too Many Attempts."
}

See API conventions for error handling, rate limits, pagination, and uploads.

Was this article helpful?

Need more help? Copy this article's details and paste them into a request on our feedback portal. You may need to sign in.

Open feedback portal

On this page